job-application-agent 3.3.0 → 3.4.1

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

@@ -12,6 +12,7 @@ import { SourceCommunityClient } from './source-community-client.mjs';
 import { normalizeCommunityJob, normalizeCommunitySource } from './source-community-schema.mjs';
 import { TelemetryClient } from './telemetry-client.mjs';
 import { jobIdentity } from './telemetry-schema.mjs';
+import { CloudStateClient, defaultCloudConfigPath, enableCloudUpdateGuard, saveCloudConfig } from './cloud-state-client.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']);
@@ -37,6 +38,10 @@ const SOURCE_CATALOG_URL = new URL('../references/SOURCES.json', import.meta.url
 const SOURCE_CATALOG = JSON.parse(readFileSync(SOURCE_CATALOG_URL, 'utf8'));
 if (!Array.isArray(SOURCE_CATALOG)) throw new Error('The packaged source catalog is invalid.');
 const SOURCE_CATALOG_IDS = new Set(SOURCE_CATALOG.map((source) => sourceId(source.id, 'source catalog id')));
+const MIN_DISCOVERY_SOURCES = 3;
+const CONCENTRATION_THRESHOLD = 60;
+const SOURCE_BLOCKERS = new Set(['login', 'mfa', 'captcha', 'site-error', 'access-unavailable']);
+const CONCENTRATION_REASONS = new Set(['stronger-fit', 'alternatives-exhausted', 'access-blocked', 'candidate-directed']);
 const COMMUNITY_SOURCE_ID = /^community-[0-9a-f]{16}$/;
 const REQUIRED_PROFILE = ['name', 'email', 'phone', 'location', 'workAuthorization', 'roleFamilies', 'seniority', 'targetLocations', 'workModes', 'submissionMode', 'yearsExperience', 'autoSubmitMinScore', 'manualReviewMinScore', 'minMustHaveCoverage'];
 const STRING_PROFILE_FIELDS = new Set(['name', 'email', 'phone', 'location', 'workAuthorization', 'linkedin', 'github', 'portfolio', 'availability', 'currentCompensation', 'targetCompensation', 'submissionMode']);
@@ -63,6 +68,17 @@ function stateDir() {
 }
 
 const secretStore = createSecretStore({ stateDir });
+const cloudState = new CloudStateClient({ stateDir: stateDir(), configPath: process.env.JOB_APPLICATION_AGENT_CLOUD_CONFIG ?? defaultCloudConfigPath() });
+
+function cachedCloudProfileRaw() {
+  try {
+    const config = JSON.parse(readFileSync(process.env.JOB_APPLICATION_AGENT_CLOUD_CONFIG ?? defaultCloudConfigPath(), 'utf8'));
+    if (config.version !== 2) return null;
+    return object(JSON.parse(readFileSync(join(stateDir(), 'cloud-profile-cache.json'), 'utf8')), 'profile');
+  } catch {
+    return null;
+  }
+}
 
 export function durationBucket(milliseconds) {
   if (milliseconds < 1_000) return 'under-1s';
@@ -600,6 +616,8 @@ export function buildReview(entries, outcomeEntries = [], acknowledgements = [],
 }
 
 function storedProfileRaw() {
+  const cloudProfile = cachedCloudProfileRaw();
+  if (cloudProfile) return cloudProfile;
   try { return object(JSON.parse(secretStore.readProfile()), 'profile'); } catch (error) {
     if (/missing or unreadable|could not read|could not store|Windows profile storage|not supported on this platform|secret-tool is not installed/i.test(error.message)) throw error;
     throw new Error('The stored profile is missing or unreadable. Run profile set again.');
@@ -859,6 +877,7 @@ async function autonomyGrant(input) {
   for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`Unknown autonomy grant property: ${key}.`);
   if (value.mode !== 'routine-auto') throw new Error('autonomy grant mode must be routine-auto.');
   const grant = { version: 1, enabled: true, mode: 'routine-auto', scopes: [...AUTONOMY_SCOPES], grantedAt: new Date().toISOString() };
+  if (await cloudState.configured()) await cloudState.putDocumentCurrent('autonomy', grant);
   const file = join(await ensureStateDir(), 'autonomy.json');
   await writePrivateJson(file, grant);
   return autonomyView(grant);
@@ -868,14 +887,21 @@ async function autonomyRevoke() {
   const file = join(await ensureStateDir(), 'autonomy.json');
   const current = await readPrivateJson(file, { version: 1, enabled: false });
   const revoked = { version: 1, enabled: false, revokedAt: new Date().toISOString(), ...(current.grantedAt ? { grantedAt: current.grantedAt } : {}) };
+  if (await cloudState.configured()) await cloudState.putDocumentCurrent('autonomy', revoked);
   await writePrivateJson(file, revoked);
   return autonomyView(revoked);
 }
 
 async function storeProfile(profileInput) {
   const profile = validateProfile(profileInput);
-  if (process.platform === 'win32') await ensureStateDir();
-  secretStore.writeProfile(JSON.stringify(profile));
+  if (await cloudState.configured()) {
+    const dir = await ensureStateDir();
+    await cloudState.putDocumentCurrent('profile', profile);
+    await writePrivateJson(join(dir, 'cloud-profile-cache.json'), profile);
+  } else {
+    if (process.platform === 'win32') await ensureStateDir();
+    secretStore.writeProfile(JSON.stringify(profile));
+  }
   return profile;
 }
 
@@ -922,11 +948,23 @@ async function importResume(source) {
   await chmod(target, 0o600);
   const metadata = { source: sourceLabel, importedAt: new Date().toISOString(), sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length };
   await writeFile(join(dir, 'resume.json'), `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+  if (await cloudState.configured()) {
+    await cloudState.putFileCurrent('resume.pdf', bytes);
+    await cloudState.putFileCurrent('resume.json', Buffer.from(JSON.stringify(metadata)));
+  }
   return { path: target, sha256: metadata.sha256, bytes: metadata.bytes };
 }
 
 async function canonicalResumePath() {
   const target = join(await ensureStateDir(), 'resume.pdf');
+  if (await cloudState.configured()) {
+    try { await cloudState.fetchResume(); }
+    catch (error) {
+      // Cached research and browser preparation remain usable during an
+      // outage. Integrity, authentication, and checksum failures still stop.
+      if (!/^Cloud state unavailable:/.test(error.message)) throw error;
+    }
+  }
   try {
     const details = await stat(target);
     if (!details.isFile()) throw new Error('Canonical resume path is not a file. Import the resume again.');
@@ -1005,7 +1043,7 @@ async function ledgerCheck(candidate) {
   return duplicateResult(entries, candidate, outcomes);
 }
 
-async function ledgerAdd(entryInput, duplicateOverride, companyReapplyOverride) {
+async function ledgerAdd(entryInput, duplicateOverride, companyReapplyOverride, cloudIntent = null) {
   const entry = validateLedgerEntry(entryInput);
   return withStateLock('applications', async (dir) => {
     const file = join(dir, 'applications.ndjson');
@@ -1035,15 +1073,30 @@ async function ledgerAdd(entryInput, duplicateOverride, companyReapplyOverride)
       await appendFile(roundsFile, `${JSON.stringify({ type: 'submission-confirmed', roundId: entry.roundId, applicationId: entry.id, occurredAt: entry.submittedAt })}\n`, { mode: 0o600 });
       await chmod(roundsFile, 0o600);
     }
-    return { recorded: storedEntry.id, review: buildReview([...entries, storedEntry]) };
+    if (await cloudState.configured()) {
+      if (cloudIntent?.intentId && cloudIntent?.leaseId) {
+        await cloudState.confirmIntent(cloudIntent.intentId, storedEntry, cloudIntent.leaseId, `application:${storedEntry.id}:${storedEntry.submittedAt}`);
+      } else {
+        await cloudState.appendRecord('applications', storedEntry, { recordKey: storedEntry.id, idempotencyKey: `application:${storedEntry.id}:${storedEntry.submittedAt}`, occurredAt: storedEntry.submittedAt, queueOnFailure: true });
+        if (entry.roundId) await cloudState.appendRecord('rounds', { type: 'submission-confirmed', roundId: entry.roundId, applicationId: entry.id, occurredAt: entry.submittedAt }, { recordKey: entry.roundId, idempotencyKey: `round-confirmation:${entry.roundId}:${entry.id}`, occurredAt: entry.submittedAt, queueOnFailure: true });
+      }
+    }
+    return { recorded: storedEntry.id, review: buildReview([...entries, storedEntry]), ...(cloudIntent ? { cloudIntent: cloudIntent.intentId } : {}) };
   });
 }
 
+async function appendCloudEvent(name, event) {
+  if (!await cloudState.configured()) return;
+  const key = event.id ?? event.roundId ?? event.applicationId ?? randomUUID();
+  await cloudState.appendRecord(name, event, { recordKey: key, idempotencyKey: `${name}:${createHash('sha256').update(JSON.stringify(event)).digest('hex')}`, occurredAt: event.occurredAt, queueOnFailure: true });
+}
+
 async function appendPrivateEvent(name, event) {
   return withStateLock(name, async (dir) => {
     const file = join(dir, `${name}.ndjson`);
     await appendFile(file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
     await chmod(file, 0o600);
+    if (['rounds', 'discovery', 'attention', 'friction'].includes(name)) await appendCloudEvent(name, event);
     return event;
   });
 }
@@ -1065,7 +1118,84 @@ async function roundStart(input) {
     occurredAt: isoDate(value.startedAt, 'round.startedAt'),
   };
   await appendPrivateEvent('rounds', event);
-  return { roundId: event.roundId, requestedCount: event.requestedCount, startedAt: event.occurredAt, completed: false };
+  return { roundId: event.roundId, requestedCount: event.requestedCount, startedAt: event.occurredAt, completed: false, discoveryPolicy: { minSources: MIN_DISCOVERY_SOURCES, concentrationThresholdPercent: CONCENTRATION_THRESHOLD }, nextStep: 'Search at least 3 distinct relevant discovery sources, record searches or blockers with round source --stdin, and review round status before applying.' };
+}
+
+function discoveryGroup(id) {
+  // Two views of the same hiring network do not demonstrate independent coverage.
+  if (['yc-work-at-a-startup', 'yc-company-directory'].includes(id)) return 'yc';
+  return id;
+}
+
+function discoverySummary(events, applications, completion) {
+  const latest = new Map();
+  const searchedIds = new Set();
+  const attribution = new Map();
+  for (const event of events.filter((item) => item.type === 'source-checked')) {
+    latest.set(event.sourceId, event);
+    if (event.status === 'searched') searchedIds.add(event.sourceId);
+    for (const id of event.applicationIds ?? []) attribution.set(id, event.sourceId);
+  }
+  const sources = [...latest.values()];
+  const eligible = sources.filter((item) => !['recruiter-inbound', 'user-supplied-leads'].includes(item.sourceId));
+  const attempted = new Set(eligible.map((item) => discoveryGroup(item.sourceId)));
+  const searched = new Set(eligible.filter((item) => searchedIds.has(item.sourceId)).map((item) => discoveryGroup(item.sourceId)));
+  const distribution = new Map();
+  let unattributedCount = 0;
+  for (const entry of applications) {
+    const source = entry.discoverySourceId ?? attribution.get(entry.id);
+    if (!source || !searchedIds.has(source)) { unattributedCount++; continue; }
+    const group = discoveryGroup(source);
+    distribution.set(group, (distribution.get(group) ?? 0) + 1);
+  }
+  const maxCount = Math.max(0, ...distribution.values());
+  const maxSourceSharePercent = applications.length ? Math.round(maxCount / applications.length * 100) : 0;
+  return {
+    minSources: MIN_DISCOVERY_SOURCES,
+    attemptedSourceCount: attempted.size,
+    searchedSourceCount: searched.size,
+    blockedSourceCount: [...attempted].filter((id) => !searched.has(id)).length,
+    coverageSatisfied: attempted.size >= MIN_DISCOVERY_SOURCES && searched.size > 0,
+    sources: sources.map(({ sourceId, status, reviewedCount, qualifiedCount, blocker, evidence }) => ({ sourceId, status, searchedDuringRound: searchedIds.has(sourceId), reviewedCount, qualifiedCount, ...(blocker ? { blocker } : {}), evidence })),
+    submissionDistribution: [...distribution].map(([sourceId, count]) => ({ sourceId, count })),
+    unattributedCount,
+    maxSourceSharePercent,
+    concentrationNeedsExplanation: applications.length > 0 && maxCount / applications.length * 100 > CONCENTRATION_THRESHOLD,
+    ...(completion?.concentrationReason ? { concentrationReason: completion.concentrationReason, concentrationEvidence: completion.concentrationEvidence } : {}),
+  };
+}
+
+async function roundSource(input) {
+  const value = object(input, 'source coverage');
+  const allowed = new Set(['roundId', 'sourceId', 'status', 'reviewedCount', 'qualifiedCount', 'blocker', 'evidence', 'applicationIds']);
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`Unknown source coverage property: ${key}.`);
+  const sourceId = knownDiscoverySourceId(value.sourceId, 'coverage.sourceId');
+  const status = string(value.status, 'coverage.status', 20);
+  if (!['searched', 'blocked'].includes(status)) throw new Error('coverage.status must be searched or blocked.');
+  const reviewedCount = integer(value.reviewedCount, 'coverage.reviewedCount', 0, 10000);
+  const qualifiedCount = integer(value.qualifiedCount, 'coverage.qualifiedCount', 0, reviewedCount);
+  const blocker = value.blocker == null ? null : string(value.blocker, 'coverage.blocker', 40);
+  if (status === 'blocked' && (!SOURCE_BLOCKERS.has(blocker) || reviewedCount !== 0 || qualifiedCount !== 0)) throw new Error('Blocked sources require a documented blocker and zero counts.');
+  if (status === 'searched' && blocker != null) throw new Error('Searched sources cannot have a blocker.');
+  const evidence = string(value.evidence, 'coverage.evidence', 2000);
+  const applicationIds = value.applicationIds == null ? [] : [...new Set(stringArray(value.applicationIds, 'coverage.applicationIds'))];
+  if (applicationIds.length > 1000 || (status === 'blocked' && applicationIds.length)) throw new Error('Invalid coverage.applicationIds.');
+  const event = await withStateLock('rounds', async (dir) => {
+    const round = await roundStatus(string(value.roundId, 'coverage.roundId', 180));
+    if (round.completed) throw new Error('Cannot record coverage for a completed round.');
+    const applications = await jsonLines(join(dir, 'applications.ndjson'));
+    for (const id of applicationIds) {
+      const entry = applications.find((item) => item.id === id && item.roundId === round.roundId && item.status === 'submitted');
+      if (!entry || (entry.discoverySourceId && entry.discoverySourceId !== sourceId)) throw new Error('Coverage attribution must match a confirmed application in this round and its saved source.');
+    }
+    const event = { type: 'source-checked', roundId: round.roundId, sourceId, status, reviewedCount, qualifiedCount, evidence, applicationIds, ...(blocker ? { blocker } : {}), occurredAt: new Date().toISOString() };
+    const file = join(dir, 'rounds.ndjson');
+    await appendFile(file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+    await chmod(file, 0o600);
+    return event;
+  });
+  await appendCloudEvent('rounds', event);
+  return event;
 }
 
 function replayAttention(events, roundId = null) {
@@ -1135,7 +1265,8 @@ async function roundStatus(roundId = null) {
   if (!id) throw new Error('No application round has been started.');
   const started = starts.find((event) => event.roundId === id);
   if (!started) throw new Error('Application round was not found.');
-  const applications = (await jsonLines(join(dir, 'applications.ndjson'))).filter((entry) => entry.roundId === id && entry.status === 'submitted');
+  const matching = (await jsonLines(join(dir, 'applications.ndjson'))).filter((entry) => entry.roundId === id && entry.status === 'submitted');
+  const applications = [...new Map(matching.map((entry, index) => [canonicalApplicationKey(entry, String(index)), entry])).values()];
   const confirmedCount = new Set(applications.map((entry, index) => canonicalApplicationKey(entry, String(index)))).size;
   const attention = await attentionList(id);
   const completion = events.find((event) => event.type === 'completed' && event.roundId === id);
@@ -1146,6 +1277,7 @@ async function roundStatus(roundId = null) {
     remainingCount: Math.max(0, started.requestedCount - confirmedCount),
     blockedCount: attention.count,
     completed: Boolean(completion),
+    discovery: discoverySummary(events.filter((event) => event.roundId === id), applications, completion),
     startedAt: started.occurredAt,
     ...(completion ? { completedAt: completion.occurredAt } : {}),
   };
@@ -1153,14 +1285,28 @@ async function roundStatus(roundId = null) {
 
 async function roundComplete(input) {
   const value = object(input, 'round completion');
-  const allowed = new Set(['roundId', 'completedAt']);
+  const allowed = new Set(['roundId', 'completedAt', 'concentrationReason', 'concentrationEvidence']);
   for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`Unknown round completion property: ${key}.`);
-  const status = await roundStatus(string(value.roundId, 'round.roundId', 180));
-  if (status.completed) return status;
-  if (status.confirmedCount < status.requestedCount) throw new Error(`Round requires ${status.requestedCount} confirmed submissions before completion.`);
-  const event = { type: 'completed', roundId: status.roundId, occurredAt: isoDate(value.completedAt, 'round.completedAt') };
-  await appendPrivateEvent('rounds', event);
-  return { ...status, completed: true, completedAt: event.occurredAt };
+  // Use the same lock order as ledger writes so completion cannot race a confirmed submission.
+  const result = await withStateLock('applications', () => withStateLock('rounds', async (dir) => {
+    const status = await roundStatus(string(value.roundId, 'round.roundId', 180));
+    if (status.completed) return { ...status, completionRecorded: false };
+    if (status.confirmedCount < status.requestedCount) throw new Error(`Round requires ${status.requestedCount} confirmed submissions before completion.`);
+    if (!status.discovery.coverageSatisfied) throw new Error('Round requires attempts across at least 3 distinct discovery sources, including at least one searched source. Record coverage and blockers with round source --stdin.');
+    if (status.discovery.unattributedCount) throw new Error('Round requires discovery source attribution for every confirmed submission. Supply missing attribution using round source applicationIds; do not rewrite the ledger.');
+    let explanation = {};
+    if (status.discovery.concentrationNeedsExplanation || value.concentrationReason != null || value.concentrationEvidence != null) {
+      if (!CONCENTRATION_REASONS.has(value.concentrationReason)) throw new Error('Source concentration requires a documented concentrationReason and private concentrationEvidence.');
+      explanation = { concentrationReason: value.concentrationReason, concentrationEvidence: string(value.concentrationEvidence, 'round.concentrationEvidence', 2000) };
+    }
+    const event = { type: 'completed', roundId: status.roundId, occurredAt: isoDate(value.completedAt, 'round.completedAt'), ...explanation };
+    const file = join(dir, 'rounds.ndjson');
+    await appendFile(file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+    await chmod(file, 0o600);
+    return { ...status, discovery: { ...status.discovery, ...explanation }, completed: true, completionRecorded: true, completedAt: event.occurredAt };
+  }));
+  if (result.completionRecorded) await appendCloudEvent('rounds', { type: 'completed', roundId: result.roundId, occurredAt: result.completedAt, ...(result.discovery.concentrationReason ? { concentrationReason: result.discovery.concentrationReason, concentrationEvidence: result.discovery.concentrationEvidence } : {}) });
+  return result;
 }
 
 async function frictionRecord(input) {
@@ -1237,6 +1383,14 @@ async function ledgerOutcome(outcomeInput) {
     return { stored: true, enriched };
   });
   const applications = await jsonLines(join(await ensureStateDir(), 'applications.ndjson'));
+  if (storage.stored && await cloudState.configured()) {
+    await cloudState.appendRecord('outcomes', event, {
+      recordKey: event.id,
+      idempotencyKey: `outcome:${event.id}:${event.status}:${event.occurredAt}:${createHash('sha256').update(JSON.stringify(event)).digest('hex')}`,
+      occurredAt: event.occurredAt,
+      queueOnFailure: true,
+    });
+  }
   return { result: { recorded: storage.stored, duplicate: !storage.stored, enriched: storage.enriched, recordedOutcome: event.id, status }, application: applications.find((entry) => entry.id === event.id) ?? null, event };
 }
 
@@ -1259,9 +1413,62 @@ async function ledgerReviewAcknowledge(input) {
     await appendFile(file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
     await chmod(file, 0o600);
   });
+  if (await cloudState.configured()) await cloudState.appendRecord('reviews', event, { recordKey: reviewedAt, idempotencyKey: `review:${reviewedAt}`, occurredAt: reviewedAt, queueOnFailure: true });
   return { acknowledged: true, ...event };
 }
 
+async function prepareCloudState(area, action) {
+  if (!await cloudState.configured() || area === 'cloud') return;
+  try {
+    await cloudState.reconcile({ dryRun: false, provenance: 'automatic-recovery' });
+    await cloudState.refreshDocumentCaches();
+  } catch (error) {
+    // New submissions still fail closed because lease and intent operations
+    // call the cloud directly. Local checks, research, and observed-result
+    // ledger appends can continue and queue their idempotent recovery writes.
+    if (!/^Cloud state unavailable:/.test(error.message)) throw error;
+  }
+}
+
+async function cloudCommand(action, value) {
+  if (action === 'configure' && value === '--stdin') {
+    const configured = await saveCloudConfig(await jsonStdin(), { configPath: process.env.JOB_APPLICATION_AGENT_CLOUD_CONFIG ?? defaultCloudConfigPath() });
+    const updateGuard = await enableCloudUpdateGuard();
+    return { configured: true, url: configured.url, clientId: configured.clientId ?? null, clientName: configured.clientName ?? null, token: configured.token, updateGuard };
+  }
+  if (action === 'status' && value == null) return cloudState.status();
+  if (action === 'reconcile' && value === '--dry-run') return cloudState.reconcile({ dryRun: true });
+  if (action === 'reconcile' && value == null) return cloudState.reconcile({ dryRun: false });
+  if (action === 'export') return cloudState.exportTo(value ?? null);
+  if (action === 'lease-acquire' && value == null) {
+    const lease = await cloudState.acquireLease();
+    await writePrivateJson(join(await ensureStateDir(), 'cloud-lease.json'), lease);
+    return lease;
+  }
+  if (action === 'lease-renew' && value == null) {
+    const lease = await readPrivateJson(join(await ensureStateDir(), 'cloud-lease.json'), null);
+    if (!lease?.leaseId) throw new Error('No local cloud lease is recorded. Run cloud lease-acquire.');
+    const renewed = await cloudState.renewLease(lease.leaseId);
+    await writePrivateJson(join(await ensureStateDir(), 'cloud-lease.json'), renewed);
+    return renewed;
+  }
+  if (action === 'lease-release' && value == null) {
+    const lease = await readPrivateJson(join(await ensureStateDir(), 'cloud-lease.json'), null);
+    if (!lease?.leaseId) throw new Error('No local cloud lease is recorded.');
+    return cloudState.releaseLease(lease.leaseId);
+  }
+  if (action === 'intent-prepare' && value === '--stdin') return cloudState.createIntent(await jsonStdin());
+  if (action === 'intent-sent' && value === '--stdin') {
+    const input = await jsonStdin();
+    return cloudState.markIntentSentUnverified(string(input.intentId, 'intentId', 200), string(input.leaseId, 'leaseId', 200));
+  }
+  if (action === 'intent-confirm' && value === '--stdin') {
+    const input = await jsonStdin();
+    return cloudState.confirmIntent(string(input.intentId, 'intentId', 200), object(input.application, 'application'), string(input.leaseId, 'leaseId', 200), input.idempotencyKey);
+  }
+  throw new Error('Usage: cloud status|configure --stdin|reconcile [--dry-run]|export [path]|lease-acquire|lease-renew|lease-release|intent-prepare --stdin|intent-sent --stdin|intent-confirm --stdin');
+}
+
 function print(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
@@ -1309,6 +1516,11 @@ function roundCompletedTelemetry(round) {
       pausedCount: round.blockedCount,
       errorCount: 0,
       durationBucket: durationBucket(Math.max(0, Date.parse(round.completedAt) - Date.parse(round.startedAt))),
+      attemptedSourceCount: round.discovery.attemptedSourceCount,
+      searchedSourceCount: round.discovery.searchedSourceCount,
+      blockedSourceCount: round.discovery.blockedSourceCount,
+      maxSourceSharePercent: round.discovery.maxSourceSharePercent,
+      ...(round.discovery.concentrationReason ? { concentrationReason: round.discovery.concentrationReason } : {}),
     },
   };
 }
@@ -1316,7 +1528,8 @@ function roundCompletedTelemetry(round) {
 async function executeCommand([area, action, value], telemetry, session, community) {
   const domainEvents = [];
   let result;
-  if (area === 'profile' && action === 'set' && value === '--stdin') {
+  if (area === 'cloud') result = await cloudCommand(action, value);
+  else if (area === 'profile' && action === 'set' && value === '--stdin') {
     const profile = await jsonStdin();
     result = await profileSet(profile);
   } else if (area === 'profile' && action === 'migrate' && value === '--stdin') {
@@ -1338,7 +1551,7 @@ async function executeCommand([area, action, value], telemetry, session, communi
     const input = await jsonStdin();
     const telemetryDetails = validateSubmissionTelemetry(input.telemetry);
     const entry = validateLedgerEntry(input);
-    result = await ledgerAdd(entry, input.duplicateOverride, input.companyReapplyOverride);
+    result = await ledgerAdd(entry, input.duplicateOverride, input.companyReapplyOverride, input.cloudIntentId && input.cloudLeaseId ? { intentId: input.cloudIntentId, leaseId: input.cloudLeaseId } : null);
     result.communityJob = await communityJobsSync(community, { limit: 1, applicationIds: [entry.id] });
     domainEvents.push(await telemetryApplicationSubmitted(entry, telemetryDetails));
   } else if (area === 'ledger' && action === 'outcome' && value === '--stdin') {
@@ -1356,10 +1569,18 @@ async function executeCommand([area, action, value], telemetry, session, communi
   else if (area === 'autonomy' && action === 'preview' && value == null) result = await autonomyStatus();
   else if (area === 'autonomy' && action === 'revoke' && value == null) result = await autonomyRevoke();
   else if (area === 'round' && action === 'start' && value === '--stdin') result = await roundStart(await jsonStdin());
+  else if (area === 'round' && action === 'source' && value === '--stdin') {
+    result = await roundSource(await jsonStdin());
+    domainEvents.push({ event: 'source_checked', properties: {
+      sourceId: result.sourceId.startsWith('community-') ? 'community' : result.sourceId,
+      status: result.status, reviewedCount: result.reviewedCount, qualifiedCount: result.qualifiedCount,
+      ...(result.blocker ? { blocker: result.blocker } : {}),
+    } });
+  }
   else if (area === 'round' && action === 'status') result = await roundStatus(value ?? null);
   else if (area === 'round' && action === 'complete' && value === '--stdin') {
     result = await roundComplete(await jsonStdin());
-    domainEvents.push(roundCompletedTelemetry(result));
+    if (result.completionRecorded) domainEvents.push(roundCompletedTelemetry(result));
   } else if (area === 'sources' && action === 'list' && value == null) {
     await syncAllCommunityData(community);
     result = await sourcesList({}, await community.list());
@@ -1382,7 +1603,7 @@ async function executeCommand([area, action, value], telemetry, session, communi
   else if (area === 'attention' && action === 'resolve' && value === '--stdin') result = await attentionResolve(await jsonStdin());
   else if (area === 'friction' && action === 'record' && value === '--stdin') result = await frictionRecord(await jsonStdin());
   else if (area === 'friction' && action === 'list' && value == null) result = await frictionList();
-  else throw new Error('Usage: profile set|migrate --stdin; profile check|field <name>; resume import <url-or-pdf>|path; score --stdin; ledger check|add|outcome|review-ack --stdin; ledger review; autonomy grant --stdin|status|preview|revoke; round start|complete --stdin|status [round-id]; sources list [--stdin]|jobs [--stdin]|suggest --stdin|pending|sync|sharing status|enable|disable|reset; attention add|resolve --stdin|list; friction record --stdin|list; telemetry status|enable|disable|reset|preview --stdin|record --stdin');
+  else throw new Error('Usage: cloud status|configure --stdin|reconcile [--dry-run]|export [path]|lease-acquire|lease-renew|lease-release|intent-prepare --stdin|intent-sent --stdin|intent-confirm --stdin; profile set|migrate --stdin; profile check|field <name>; resume import <url-or-pdf>|path; score --stdin; ledger check|add|outcome|review-ack --stdin; ledger review; autonomy grant --stdin|status|preview|revoke; round start|source|complete --stdin|status [round-id]; sources list [--stdin]|jobs [--stdin]|suggest --stdin|pending|sync|sharing status|enable|disable|reset; attention add|resolve --stdin|list; friction record --stdin|list; telemetry status|enable|disable|reset|preview --stdin|record --stdin');
   for (const event of domainEvents) await telemetry.record(event, session);
   return result;
 }
@@ -1403,9 +1624,14 @@ async function recordInstallationStart(telemetry, session) {
 
 async function main(args) {
   const [area, action, value] = args;
-  const telemetry = new TelemetryClient({ stateDir: stateDir() });
+  const telemetry = new TelemetryClient({ stateDir: stateDir(), readIdentity: () => {
+    const profile = storedProfileRaw();
+    // Only explicit saved fields; no resume parsing, conversation scraping, or full profile payload.
+    return Object.fromEntries(['name', 'email'].filter((key) => typeof profile[key] === 'string' && profile[key].trim()).map((key) => [key, profile[key]]));
+  } });
   const community = new SourceCommunityClient({ stateDir: stateDir() });
   if (area === 'telemetry') {
+    if (action === 'identity' && ['status', 'enable', 'disable'].includes(value) && args.length === 3) return print(await telemetry.configureIdentity(value));
     if (['status', 'enable', 'disable', 'reset'].includes(action) && value == null) return print(await telemetry.configure(action));
     if (action === 'preview' && value === '--stdin') return print(await telemetry.preview(await jsonStdin()));
     if (action === 'record' && value === '--stdin') {
@@ -1413,9 +1639,11 @@ async function main(args) {
       await recordInstallationStart(telemetry, session);
       return print(await telemetry.record(await jsonStdin(), session, { strict: true }));
     }
-    throw new Error('Usage: telemetry status|enable|disable|reset|preview --stdin|record --stdin');
+    throw new Error('Usage: telemetry status|enable|disable|reset|preview --stdin|record --stdin; telemetry identity status|enable|disable');
   }
 
+  await prepareCloudState(area, action);
+
   const command = commandCategory(args);
   const session = await telemetry.beginCommand(command);
   await recordInstallationStart(telemetry, session);

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

@@ -1,13 +1,14 @@
 import { chmod, mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { createTelemetryEnvelope, jobIdentity, validateEvent } from './telemetry-schema.mjs';
+import { createTelemetryEnvelope, jobIdentity, validateEvent, validateTelemetryIdentity } from './telemetry-schema.mjs';
 import { SKILL_VERSION } from './version.mjs';
 
 export { SKILL_VERSION };
 
 export const DEFAULT_TELEMETRY_ENDPOINT = process.env.JOB_APPLICATION_AGENT_TELEMETRY_URL ?? 'https://job-application-agent-telemetry.varora1406.workers.dev';
-export const TELEMETRY_NOTICE = 'Anonymous usage analytics are enabled by default. They include structured job and workflow metrics, but never your identity, resume, prompts, form answers, browser data, or candidate profile. Run `telemetry disable` to opt out or `telemetry preview` to inspect an event.\n';
+export const TELEMETRY_NOTICE = 'Usage analytics are enabled by default. They include structured job and workflow metrics. Name and email sharing has a separate disclosure and opt-out. Resume content, other profile fields, prompts, form answers, browser data, and raw errors are never sent. Run `telemetry disable` to stop all analytics or `telemetry preview` to inspect an event.\n';
+export const IDENTITY_NOTICE = 'Name and email sharing is enabled by default. Starting with the next command, JobAgent shares the name and email explicitly saved in your candidate profile with the maintainer through private PostHog usage analytics for support and product improvement. Run `telemetry identity disable` to keep future analytics anonymous, or `telemetry disable` to stop all analytics. Opting out rotates the analytics ID; previously collected data is retained under the analytics retention policy.\n';
 
 const CONFIG_VERSION = 1;
 const CONFIG_FILE = 'telemetry.json';
@@ -38,13 +39,14 @@ async function writePrivate(file, value) {
 }
 
 export class TelemetryClient {
-  constructor({ stateDir, endpoint = DEFAULT_TELEMETRY_ENDPOINT, fetch: fetchFn = globalThis.fetch, stderr = (value) => process.stderr.write(value), now = () => new Date(), timeoutMs = Number(process.env.JOB_APPLICATION_AGENT_TELEMETRY_TIMEOUT_MS ?? 3000) }) {
+  constructor({ stateDir, endpoint = DEFAULT_TELEMETRY_ENDPOINT, fetch: fetchFn = globalThis.fetch, stderr = (value) => process.stderr.write(value), now = () => new Date(), timeoutMs = Number(process.env.JOB_APPLICATION_AGENT_TELEMETRY_TIMEOUT_MS ?? 3000), readIdentity = () => undefined }) {
     this.stateDir = stateDir;
     this.endpoint = endpoint.replace(/\/$/, '');
     this.fetch = fetchFn;
     this.stderr = stderr;
     this.now = now;
     this.timeoutMs = timeoutMs;
+    this.readIdentity = readIdentity;
   }
 
   get configPath() { return join(this.stateDir, CONFIG_FILE); }
@@ -57,7 +59,7 @@ export class TelemetryClient {
   async readConfig() {
     try {
       const value = JSON.parse(await readFile(this.configPath, 'utf8'));
-      return { version: CONFIG_VERSION, enabled: value.enabled !== false, disclosed: value.disclosed === true, graceConsumed: value.graceConsumed === true, installationEventPending: value.installationEventPending === true, installationId: value.installationId ?? null, token: value.token ?? null, tokenExpiresAt: value.tokenExpiresAt ?? null };
+      return { version: CONFIG_VERSION, enabled: value.enabled !== false, disclosed: value.disclosed === true, graceConsumed: value.graceConsumed === true, installationEventPending: value.installationEventPending === true, installationId: value.installationId ?? null, token: value.token ?? null, tokenExpiresAt: value.tokenExpiresAt ?? null, identityEnabled: value.identityEnabled !== false, identityDisclosed: value.identityDisclosed === true };
     } catch (error) {
       if (error.code === 'ENOENT') return null;
       return { version: CONFIG_VERSION, enabled: false, disclosed: true, graceConsumed: true, installationEventPending: false, installationId: null, token: null, tokenExpiresAt: null };
@@ -101,7 +103,13 @@ export class TelemetryClient {
       config.graceConsumed = true;
       await this.saveConfig(config);
     }
-    return { command, enabled: config.enabled, allowSend: config.enabled && allowSend, installationEventPending: config.installationEventPending === true };
+    const allowIdentity = config.identityEnabled !== false && config.identityDisclosed === true;
+    if (config.enabled && config.identityEnabled !== false && !config.identityDisclosed) {
+      this.stderr(IDENTITY_NOTICE);
+      config.identityDisclosed = true;
+      await this.saveConfig(config);
+    }
+    return { command, enabled: config.enabled, allowSend: config.enabled && allowSend, allowIdentity, installationEventPending: config.installationEventPending === true };
   }
 
   async credentials(config) {
@@ -128,13 +136,17 @@ export class TelemetryClient {
       if (session.unavailable) return { sent: false, reason: 'unavailable' };
       let config = await this.readConfig();
       if (!config?.enabled) return { sent: false, reason: 'disabled' };
+      let identity;
+      if (session.allowIdentity === true && config.identityEnabled !== false && config.identityDisclosed === true) {
+        try { identity = validateTelemetryIdentity(await this.readIdentity()); } catch { /* Missing or invalid identity never blocks anonymous analytics. */ }
+      }
       config = await this.credentials(config);
-      const payload = createTelemetryEnvelope({ installationId: config.installationId, token: config.token, event, skillVersion: SKILL_VERSION });
+      const payload = createTelemetryEnvelope({ installationId: config.installationId, token: config.token, event, skillVersion: SKILL_VERSION, identity });
       let response = await this.fetch(`${this.endpoint}/v1/events`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload), signal: AbortSignal.timeout(this.timeoutMs) });
       if (response.status === 401) {
         config.tokenExpiresAt = null;
         config = await this.credentials(config);
-        response = await this.fetch(`${this.endpoint}/v1/events`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(createTelemetryEnvelope({ installationId: config.installationId, token: config.token, event, skillVersion: SKILL_VERSION })), signal: AbortSignal.timeout(this.timeoutMs) });
+        response = await this.fetch(`${this.endpoint}/v1/events`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(createTelemetryEnvelope({ installationId: config.installationId, token: config.token, event, skillVersion: SKILL_VERSION, identity })), signal: AbortSignal.timeout(this.timeoutMs) });
       }
       if (!response.ok) {
         session.unavailable = true;
@@ -154,7 +166,22 @@ export class TelemetryClient {
 
   async status() {
     const config = await this.readConfig();
-    return { enabled: config?.enabled ?? true, disclosed: config?.disclosed ?? false, hasInstallationId: Boolean(config?.installationId), endpoint: this.endpoint, schemaVersion: 1 };
+    return { enabled: config?.enabled ?? true, disclosed: config?.disclosed ?? false, hasInstallationId: Boolean(config?.installationId), installationId: config?.installationId ?? null, identityEnabled: config?.identityEnabled ?? true, identityDisclosed: config?.identityDisclosed ?? false, endpoint: this.endpoint, schemaVersion: 1 };
+  }
+
+  async configureIdentity(action) {
+    if (action === 'status') return this.status();
+    if (!['enable', 'disable'].includes(action)) throw new Error('Identity action must be status, enable, or disable.');
+    const current = await this.readConfig() ?? { version: CONFIG_VERSION, enabled: true, disclosed: false, graceConsumed: true, installationEventPending: true };
+    const enabled = action === 'enable';
+    // Rotate at both boundaries to avoid identifying an earlier anonymous period.
+    if (enabled !== (current.identityEnabled !== false)) {
+      Object.assign(current, { installationId: null, token: null, tokenExpiresAt: null });
+    }
+    if (enabled && current.identityEnabled === false) current.identityDisclosed = false;
+    current.identityEnabled = enabled;
+    await this.saveConfig(current);
+    return this.status();
   }
 
   async configure(action) {

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

@@ -31,6 +31,9 @@ const FAILURE_POINTS = values('role-scope', 'company-problem', 'constraints', 'i
 const ERROR_CODES = values('invalid_input', 'network_failure', 'relay_unavailable', 'authentication_required', 'site_changed', 'upload_failed', 'submission_unconfirmed', 'rate_limited', 'internal_error');
 const MATCH_TAGS = values('role_family', 'seniority', 'skills', 'industry', 'location', 'remote', 'salary', 'ai', 'product', 'leadership', 'authorization');
 const GAP_TAGS = values('role_family', 'seniority', 'skills', 'industry', 'location', 'salary_unknown', 'salary_below', 'authorization_unclear', 'sponsorship', 'experience', 'domain', 'other');
+const DISCOVERY_SOURCE_KEYS = values('direct-company-careers', 'linkedin-jobs-feed', 'x-hiring-feed', 'yc-work-at-a-startup', 'yc-company-directory', 'hacker-news-who-is-hiring', 'we-work-remotely', 'a16z-build-jobs', 'engg-space', 'js-guru-jobs', 'linux-careers', 'indeed', 'recruiter-inbound', 'user-supplied-leads', 'community');
+const DISCOVERY_BLOCKERS = values('login', 'mfa', 'captcha', 'site-error', 'access-unavailable');
+const CONCENTRATION_REASONS = values('stronger-fit', 'alternatives-exhausted', 'access-blocked', 'candidate-directed');
 
 const text = (max, identitySafe = false) => ({ kind: 'text', max, identitySafe });
 const integer = (min, max) => ({ kind: 'integer', min, max });
@@ -43,6 +46,7 @@ const JOB = {
 };
 
 export const EVENT_SCHEMAS = {
+  source_checked: { required: { sourceId: enumValue(DISCOVERY_SOURCE_KEYS), status: enumValue(values('searched', 'blocked')), reviewedCount: integer(0, 10000), qualifiedCount: integer(0, 10000) }, optional: { blocker: enumValue(DISCOVERY_BLOCKERS) } },
   installation_started: { required: { osFamily: enumValue(values('macos', 'linux', 'windows', 'other')), nodeMajor: integer(20, 99), submissionMode: enumValue(SUBMISSION_MODES) } },
   command_completed: { required: { command: enumValue(COMMANDS), result: enumValue(RESULTS), durationBucket: enumValue(DURATIONS) } },
   job_discovered: { required: { ...JOB, source: enumValue(SOURCES), jobCountry: text(80, true), workMode: enumValue(WORK_MODES), seniority: enumValue(SENIORITIES), employmentType: enumValue(EMPLOYMENT), roleFamily: enumValue(ROLE_FAMILIES) }, optional: { salaryCurrency: { kind: 'currency' }, salaryMin: integer(0, 10000000), salaryMax: integer(0, 10000000) } },
@@ -52,7 +56,7 @@ export const EVENT_SCHEMAS = {
   application_paused: { required: { jobHash: { kind: 'hash' }, ats: enumValue(ATS), stage: enumValue(STAGES), reason: enumValue(PAUSE_REASONS) } },
   application_skipped: { required: { jobHash: { kind: 'hash' }, reason: enumValue(SKIP_REASONS), fitScore: integer(0, 100), eligibility: enumValue(ELIGIBILITY) } },
   application_submitted: { required: { ...JOB, durationBucket: enumValue(DURATIONS), fieldsFilled: integer(0, 500), shortAnswerCount: integer(0, 100), resumeUploaded: boolean, approvalMode: enumValue(APPROVAL_MODES) } },
-  round_completed: { required: { requestedCount: integer(1, 1000), submittedCount: integer(0, 1000), assessedCount: integer(0, 10000), skippedCount: integer(0, 10000), pausedCount: integer(0, 10000), errorCount: integer(0, 10000), durationBucket: enumValue(DURATIONS) } },
+  round_completed: { required: { requestedCount: integer(1, 1000), submittedCount: integer(0, 1000), assessedCount: integer(0, 10000), skippedCount: integer(0, 10000), pausedCount: integer(0, 10000), errorCount: integer(0, 10000), durationBucket: enumValue(DURATIONS) }, optional: { attemptedSourceCount: integer(0, 10000), searchedSourceCount: integer(0, 10000), blockedSourceCount: integer(0, 10000), maxSourceSharePercent: integer(0, 100), concentrationReason: enumValue(CONCENTRATION_REASONS) } },
   outcome_recorded: {
     required: { ...JOB, outcome: enumValue(OUTCOMES), daysSinceSubmission: integer(0, 3650) },
     optional: { interviewQuality: enumValue(INTERVIEW_QUALITIES), failurePoint: enumValue(FAILURE_POINTS) },
@@ -118,6 +122,11 @@ export function validateEvent(input) {
   }
   for (const [name, rule] of Object.entries(schema.optional ?? {})) if (name in input.properties) properties[name] = validateProperty(name, input.properties[name], rule);
   if (input.event === 'outcome_recorded' && properties.failurePoint && !properties.interviewQuality) throw new Error('failurePoint requires interviewQuality.');
+  if (input.event === 'source_checked') {
+    if (properties.qualifiedCount > properties.reviewedCount) throw new Error('qualifiedCount cannot exceed reviewedCount.');
+    if (properties.status === 'blocked' && (!properties.blocker || properties.reviewedCount !== 0 || properties.qualifiedCount !== 0)) throw new Error('Blocked sources require a blocker and zero counts.');
+    if (properties.status === 'searched' && properties.blocker) throw new Error('Searched sources cannot have a blocker.');
+  }
   const result = { event: input.event, properties };
   if (new TextEncoder().encode(JSON.stringify(result)).length > TELEMETRY_MAX_BYTES) throw new Error('Telemetry event exceeds 4 KB.');
   return result;
@@ -142,19 +151,37 @@ export async function jobIdentity(value) {
   return { jobHash: [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join(''), domain: new URL(canonical).hostname };
 }
 
-export function createTelemetryEnvelope({ installationId, token, event, properties, skillVersion }) {
+// Identity is a separate allowlisted envelope field, never arbitrary event input.
+export function validateTelemetryIdentity(input) {
+  if (!input || Array.isArray(input) || typeof input !== 'object') throw new Error('Telemetry identity must be an object.');
+  for (const key of Object.keys(input)) if (!['name', 'email'].includes(key)) throw new Error('Unknown telemetry identity property.');
+  const identity = {};
+  for (const [key, max] of [['name', 160], ['email', 254]]) {
+    if (!(key in input)) continue;
+    const value = input[key];
+    if (typeof value !== 'string' || !value.trim() || value.length > max || /[\x00-\x1f\x7f]/.test(value)) throw new Error('Invalid telemetry identity field.');
+    const normalized = value.trim();
+    if (key === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized)) throw new Error('Invalid telemetry identity email.');
+    identity[key] = normalized;
+  }
+  if (!Object.keys(identity).length) throw new Error('Telemetry identity must include name or email.');
+  return identity;
+}
+
+export function createTelemetryEnvelope({ installationId, token, event, properties, skillVersion, identity }) {
   if (!UUID.test(installationId)) throw new Error('installationId must be an anonymous UUID.');
   if (typeof token !== 'string' || token.length < 8 || token.length > 2048) throw new Error('token is invalid.');
   if (typeof skillVersion !== 'string' || !VERSION.test(skillVersion)) throw new Error('skillVersion is invalid.');
   const safe = validateEvent(typeof event === 'string' ? { event, properties } : event);
   const envelope = { schemaVersion: TELEMETRY_SCHEMA_VERSION, skillVersion, installationId, token, ...safe };
+  if (identity !== undefined) envelope.identity = validateTelemetryIdentity(identity);
   if (new TextEncoder().encode(JSON.stringify(envelope)).length > TELEMETRY_MAX_BYTES) throw new Error('Telemetry payload exceeds 4 KB.');
   return envelope;
 }
 
 export function validateTelemetryEnvelope(input) {
   if (!input || Array.isArray(input) || typeof input !== 'object') throw new Error('Telemetry payload must be an object.');
-  const allowed = new Set(['schemaVersion', 'skillVersion', 'installationId', 'token', 'event', 'properties']);
+  const allowed = new Set(['schemaVersion', 'skillVersion', 'installationId', 'token', 'event', 'properties', 'identity']);
   for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`Unknown telemetry envelope property: ${key}.`);
   if (input.schemaVersion !== TELEMETRY_SCHEMA_VERSION) throw new Error('Unsupported telemetry schema version.');
   return createTelemetryEnvelope(input);