@reconcrap/boss-recommend-mcp 2.1.24 → 2.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recommend-mcp",
-  "version": "2.1.24",
+  "version": "2.1.25",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",

package/src/chat-runtime-config.js

@@ -277,11 +277,13 @@ export function resolveHumanBehaviorForRun(args = {}, config = {}) {
     override.enabled = rawBehavior;
   } else if (typeof rawBehavior === "string") {
     applyHumanBehaviorProfileDefaults(override, rawBehavior);
-  } else if (rawBehavior && typeof rawBehavior === "object" && !Array.isArray(rawBehavior)) {
-    const rawProfile = readFirstOwn(rawBehavior, ["profile", "mode", "behaviorProfile", "behavior_profile"]);
-    if (rawProfile !== undefined) applyHumanBehaviorProfileDefaults(override, rawProfile);
-    Object.assign(override, rawBehavior);
-  }
+  } else if (rawBehavior && typeof rawBehavior === "object" && !Array.isArray(rawBehavior)) {
+    const rawProfile = readFirstOwn(rawBehavior, ["profile", "mode", "behaviorProfile", "behavior_profile"]);
+    if (rawProfile !== undefined) applyHumanBehaviorProfileDefaults(override, rawProfile);
+    Object.assign(override, rawBehavior);
+    const rawRestLevel = readFirstOwn(rawBehavior, ["restLevel", "rest_level"]);
+    if (rawRestLevel !== undefined) override.restLevel = rawRestLevel;
+  }
 
   const profile = readFirstOwn(args, ["human_behavior_profile", "humanBehaviorProfile"]);
   if (profile !== undefined) applyHumanBehaviorProfileDefaults(override, profile);

package/src/core/browser/index.js

@@ -2375,13 +2375,14 @@ export function resolveHumanClickPointForBox(box, {
   };
 }
 
-export async function clickPoint(client, x, y, {
-  button = "left",
-  clickCount = 1,
-  delayMs = 80,
-  humanRestEnabled = null,
-  humanInteraction = null
-} = {}) {
+export async function clickPoint(client, x, y, {
+  button = "left",
+  clickCount = 1,
+  delayMs = 80,
+  moveBeforePress = true,
+  humanRestEnabled = null,
+  humanInteraction = null
+} = {}) {
   const configured = getHumanInteractionConfig(client);
   const mergedHumanInteraction = {
     ...(configured || {}),
@@ -2390,7 +2391,11 @@ export async function clickPoint(client, x, y, {
   const humanEnabled = humanRestEnabled === true
     || humanInteraction?.enabled === true
     || (humanRestEnabled !== false && configured?.enabled === true);
-  if (humanEnabled && mergedHumanInteraction.clickMovementEnabled !== false) {
+  if (
+    moveBeforePress !== false
+    && humanEnabled
+    && mergedHumanInteraction.clickMovementEnabled !== false
+  ) {
     return simulateHumanClick(client, x, y, {
       ...mergedHumanInteraction,
       button,
@@ -2398,7 +2403,9 @@ export async function clickPoint(client, x, y, {
       delayMs
     });
   }
-  await client.Input.dispatchMouseEvent({ type: "mouseMoved", x, y, button: "none" });
+  if (moveBeforePress !== false) {
+    await client.Input.dispatchMouseEvent({ type: "mouseMoved", x, y, button: "none" });
+  }
   await client.Input.dispatchMouseEvent({ type: "mousePressed", x, y, button, clickCount });
   if (delayMs > 0) await sleep(delayMs);
   await client.Input.dispatchMouseEvent({ type: "mouseReleased", x, y, button, clickCount });

package/src/core/run/index.js

@@ -276,10 +276,11 @@ export function createRunLifecycleManager({
         });
         return;
       }
-      setStatus(entry, RUN_STATUS_FAILED, {
-        completedAt: now(),
-        error: errorDiagnostic(error, entry.run.phase)
-      });
+      setStatus(entry, RUN_STATUS_FAILED, {
+        completedAt: now(),
+        error: errorDiagnostic(error, entry.run.phase),
+        summary: error?.run_summary || entry.run.summary
+      });
     }
   }
 

package/src/core/screening/index.js

@@ -37,6 +37,33 @@ const GENDER_CODE_MAP = {
   2: "女"
 };
 
+const RECOMMEND_NETWORK_CANDIDATE_ID_KEYS = new Set([
+  "candidateid",
+  "encryptjid",
+  "encryptgeekid",
+  "gid",
+  "geekid",
+  "jid",
+  "securityid"
+]);
+
+const RECOMMEND_PLACEHOLDER_PROFILE_NAMES = new Set([
+  "-",
+  "--",
+  "boss用户",
+  "候选人",
+  "匿名",
+  "匿名候选人",
+  "匿名用户",
+  "暂无",
+  "未知",
+  "未填写",
+  "用户",
+  "求职者",
+  "牛人",
+  "保密"
+]);
+
 const LLM_THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "auto", "current"]);
 const LLM_SCREENING_STRATEGIES = new Set(["single_pass", "fast_first_verified"]);
 const FAST_FIRST_DEFAULT_FAST_MAX_TOKENS = 384;
@@ -756,6 +783,177 @@ function collectObjects(root, {
   return objects;
 }
 
+function normalizeRecommendBindingCandidateId(value = "") {
+  if (!["string", "number"].includes(typeof value)) return "";
+  const raw = normalizeText(value);
+  if (!raw) return "";
+  try {
+    return normalizeText(decodeURIComponent(raw));
+  } catch {
+    return raw;
+  }
+}
+
+function normalizeRecommendBindingName(value = "") {
+  return normalizeText(value).normalize("NFKC").toLocaleLowerCase("zh-CN");
+}
+
+function isRecommendPlaceholderProfileName(value = "") {
+  const normalized = normalizeRecommendBindingName(value);
+  return !normalized
+    || RECOMMEND_PLACEHOLDER_PROFILE_NAMES.has(normalized)
+    || /^[-—–_*＊]+$/u.test(normalized);
+}
+
+function canonicalRecommendNetworkCandidateIdKey(value = "") {
+  return String(value || "").replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+
+function collectRecommendNetworkCandidateIdEvidence(networkBody = {}, profileRoots = []) {
+  const evidence = [];
+  const seen = new Set();
+  const add = (value, source) => {
+    const candidateId = normalizeRecommendBindingCandidateId(value);
+    if (!candidateId) return;
+    const key = `${candidateId}\u0000${source}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    evidence.push({ candidate_id: candidateId, source });
+  };
+
+  const rawUrl = normalizeText(networkBody?.url);
+  if (rawUrl) {
+    try {
+      const parsedUrl = new URL(rawUrl, "https://www.zhipin.com");
+      if (/\/geek\/info(?:\/|$)/i.test(parsedUrl.pathname)) {
+        for (const [key, value] of parsedUrl.searchParams.entries()) {
+          const canonicalKey = canonicalRecommendNetworkCandidateIdKey(key);
+          if (RECOMMEND_NETWORK_CANDIDATE_ID_KEYS.has(canonicalKey)) {
+            add(value, `url_query:${canonicalKey}`);
+          }
+        }
+      }
+    } catch {
+      // An unparseable response URL cannot prove candidate identity.
+    }
+  }
+
+  for (const object of profileRoots.filter(isPlainObject)) {
+    for (const [key, value] of Object.entries(object)) {
+      const canonicalKey = canonicalRecommendNetworkCandidateIdKey(key);
+      if (!RECOMMEND_NETWORK_CANDIDATE_ID_KEYS.has(canonicalKey)) continue;
+      add(value, `payload_profile_field:${canonicalKey}`);
+    }
+  }
+
+  return evidence.slice(0, 20);
+}
+
+function collectRecommendResponseCandidateIdDiagnostics(parsedObjects = []) {
+  const ids = [];
+  for (const object of collectObjects(parsedObjects, { maxObjects: 800, maxDepth: 10 })) {
+    for (const [key, value] of Object.entries(object)) {
+      const canonicalKey = canonicalRecommendNetworkCandidateIdKey(key);
+      if (!RECOMMEND_NETWORK_CANDIDATE_ID_KEYS.has(canonicalKey)) continue;
+      const candidateId = normalizeRecommendBindingCandidateId(value);
+      if (candidateId) ids.push(candidateId);
+    }
+  }
+  return [...new Set(ids)].slice(0, 10);
+}
+
+function bindRecommendNetworkProfileToCard(parsedProfile, cardCandidate) {
+  if (!parsedProfile?.ok) return parsedProfile;
+  const expectedCandidateId = normalizeRecommendBindingCandidateId(cardCandidate?.id);
+  const expectedName = normalizeText(cardCandidate?.identity?.name);
+  const normalizedExpectedName = normalizeRecommendBindingName(expectedName);
+  const profileName = normalizeText(parsedProfile?.profile?.identity?.name);
+  const normalizedProfileName = normalizeRecommendBindingName(profileName);
+  const candidateIdEvidence = Array.isArray(parsedProfile.candidate_id_evidence)
+    ? parsedProfile.candidate_id_evidence
+    : [];
+  const observedCandidateIds = [...new Set(candidateIdEvidence.map((item) => (
+    normalizeRecommendBindingCandidateId(item?.candidate_id)
+  )).filter(Boolean))].slice(0, 5);
+  const responseObservedCandidateIds = Array.isArray(parsedProfile.response_candidate_id_diagnostics)
+    ? parsedProfile.response_candidate_id_diagnostics.slice(0, 10)
+    : [];
+  const matchedCandidateIdEvidence = candidateIdEvidence.find((item) => (
+    normalizeRecommendBindingCandidateId(item?.candidate_id) === expectedCandidateId
+  )) || null;
+  const candidateIdConflict = observedCandidateIds.length > 1;
+  const candidateIdVerified = Boolean(
+    expectedCandidateId
+    && observedCandidateIds.length === 1
+    && observedCandidateIds[0] === expectedCandidateId
+  );
+  const profileNameUsable = !isRecommendPlaceholderProfileName(profileName);
+  const expectedNameUsable = !isRecommendPlaceholderProfileName(expectedName);
+  const nameVerified = Boolean(
+    expectedNameUsable
+    && profileNameUsable
+    && normalizedProfileName === normalizedExpectedName
+  );
+  let reason = null;
+  if (!expectedCandidateId) reason = "expected_candidate_id_missing";
+  else if (!candidateIdEvidence.length) reason = "network_candidate_id_evidence_missing";
+  else if (candidateIdConflict) reason = "network_candidate_id_conflict";
+  else if (!candidateIdVerified) reason = "network_candidate_id_mismatch";
+  else if (!expectedNameUsable) reason = "expected_card_name_placeholder_or_missing";
+  else if (!profileNameUsable) reason = "network_profile_name_placeholder_or_missing";
+  else if (!nameVerified) reason = "network_profile_name_mismatch";
+
+  const binding = {
+    required: true,
+    verified: !reason,
+    reason,
+    expected_candidate_id: expectedCandidateId || null,
+    matched_candidate_id_source: candidateIdVerified
+      ? matchedCandidateIdEvidence?.source || null
+      : null,
+    observed_candidate_id_count: candidateIdEvidence.length,
+    observed_candidate_ids: observedCandidateIds,
+    response_observed_candidate_ids: responseObservedCandidateIds,
+    expected_name: expectedName || null,
+    profile_name: profileName || null,
+    exact_name: nameVerified
+  };
+  if (!reason) {
+    return {
+      ...parsedProfile,
+      candidate_binding: binding
+    };
+  }
+
+  const { profile: _excludedProfile, ...diagnostic } = parsedProfile;
+  return {
+    ...diagnostic,
+    ok: false,
+    error: "RECOMMEND_NETWORK_PROFILE_CANDIDATE_BINDING_UNVERIFIED",
+    candidate_binding: binding
+  };
+}
+
+function compactNetworkProfileCandidateBinding(binding = null) {
+  if (!binding) return null;
+  return {
+    verified: binding.verified === true,
+    reason: binding.reason || null,
+    expected_candidate_id: binding.expected_candidate_id || null,
+    matched_candidate_id_source: binding.matched_candidate_id_source || null,
+    observed_candidate_id_count: Number(binding.observed_candidate_id_count) || 0,
+    observed_candidate_ids: Array.isArray(binding.observed_candidate_ids)
+      ? binding.observed_candidate_ids.slice(0, 5)
+      : [],
+    response_observed_candidate_ids: Array.isArray(binding.response_observed_candidate_ids)
+      ? binding.response_observed_candidate_ids.slice(0, 10)
+      : [],
+    expected_name: binding.expected_name || null,
+    profile_name: binding.profile_name || null,
+    exact_name: binding.exact_name === true
+  };
+}
+
 function joinRange(start, end, fallback = "") {
   const left = parseDateLike(start);
   const right = parseDateLike(end);
@@ -889,8 +1087,29 @@ function resolveBossGeekDetail(payload = {}) {
   return found || { sourceKey: "", detail: null };
 }
 
+function resolveBossChatGeekInfoData(payload = {}) {
+  return payload?.zpData?.data
+    || payload?.data
+    || payload?.zpData?.geekInfo
+    || payload?.geekInfo
+    || null;
+}
+
+function resolveBossChatHistoryResumeObject(payload = {}) {
+  const messages = normalizeList(payload?.zpData?.messages).length
+    ? normalizeList(payload?.zpData?.messages)
+    : normalizeList(payload?.messages).length
+      ? normalizeList(payload?.messages)
+      : normalizeList(payload?.data?.messages).length
+        ? normalizeList(payload?.data?.messages)
+        : normalizeList(payload?.zpData?.data?.messages);
+  return messages
+    .map((message) => message?.body?.resume)
+    .find((resume) => resume && typeof resume === "object") || null;
+}
+
 function extractBossChatGeekInfo(payload = {}) {
-  const data = payload?.zpData?.data || payload?.data || payload?.zpData?.geekInfo || payload?.geekInfo;
+  const data = resolveBossChatGeekInfoData(payload);
   if (!data || typeof data !== "object") return null;
   if (!isBossChatProfileShape(data)) return null;
   const educationList = normalizeList(data.eduExpList);
@@ -961,17 +1180,7 @@ function extractBossChatGeekInfo(payload = {}) {
 }
 
 function extractBossChatHistoryResume(payload = {}) {
-  const messages = normalizeList(payload?.zpData?.messages).length
-    ? normalizeList(payload?.zpData?.messages)
-    : normalizeList(payload?.messages).length
-      ? normalizeList(payload?.messages)
-      : normalizeList(payload?.data?.messages).length
-        ? normalizeList(payload?.data?.messages)
-        : normalizeList(payload?.zpData?.data?.messages);
-  const resumes = messages
-    .map((message) => message?.body?.resume)
-    .filter((resume) => resume && typeof resume === "object");
-  const resume = resumes[0];
+  const resume = resolveBossChatHistoryResumeObject(payload);
   if (!resume) return null;
   const user = resume.user || {};
   const educationList = normalizeList(resume.education);
@@ -1177,6 +1386,10 @@ export function extractBossProfileFromNetworkBody(networkBody = {}) {
     tryParseJson(text),
     ...tryParseEmbeddedJsonObjects(text)
   ].filter((item) => item && typeof item === "object");
+  const responseCandidateIdDiagnostics = collectRecommendResponseCandidateIdDiagnostics(
+    parsedObjects
+  );
+  let candidateIdEvidence = collectRecommendNetworkCandidateIdEvidence(networkBody, []);
   if (!parsedObjects.length) {
     const htmlText = /<html|<body|<div|<section|<script/i.test(text) ? htmlToText(text) : "";
     if (htmlText && htmlText.length > 80) {
@@ -1191,6 +1404,8 @@ export function extractBossProfileFromNetworkBody(networkBody = {}) {
         status: networkBody.status ?? null,
         mimeType: networkBody.mimeType || null,
         text_length: text.length,
+        candidate_id_evidence: candidateIdEvidence,
+        response_candidate_id_diagnostics: responseCandidateIdDiagnostics,
         profile: {
           identity: candidate.identity,
           tags: candidate.tags,
@@ -1206,21 +1421,49 @@ export function extractBossProfileFromNetworkBody(networkBody = {}) {
     return {
       ok: false,
       error: "NETWORK_BODY_NOT_JSON",
-      text_length: text.length
+      text_length: text.length,
+      candidate_id_evidence: candidateIdEvidence,
+      response_candidate_id_diagnostics: responseCandidateIdDiagnostics
     };
   }
   let profile = null;
   let parsed = parsedObjects[0];
+  let profileBindingRoots = [];
   for (const candidateObject of parsedObjects) {
-    profile = extractBossGeekDetailInfo(candidateObject)
-      || extractBossChatGeekInfo(candidateObject)
-      || extractBossChatHistoryResume(candidateObject)
-      || extractBossProfileRecursively(candidateObject);
+    const geekDetail = resolveBossGeekDetail(candidateObject).detail;
+    if (geekDetail) {
+      profile = extractBossGeekDetailInfo(candidateObject);
+      profileBindingRoots = [
+        geekDetail,
+        geekDetail.geekBaseInfo,
+        geekDetail.baseInfo,
+        geekDetail.base
+      ].filter(isPlainObject);
+    } else {
+      const chatData = resolveBossChatGeekInfoData(candidateObject);
+      if (isBossChatProfileShape(chatData)) {
+        profile = extractBossChatGeekInfo(candidateObject);
+        profileBindingRoots = [chatData];
+      } else {
+        const historyResume = resolveBossChatHistoryResumeObject(candidateObject);
+        if (historyResume) {
+          profile = extractBossChatHistoryResume(candidateObject);
+          profileBindingRoots = [historyResume, historyResume.user].filter(isPlainObject);
+        } else {
+          profile = extractBossProfileRecursively(candidateObject);
+          profileBindingRoots = [];
+        }
+      }
+    }
     if (profile) {
       parsed = candidateObject;
       break;
     }
   }
+  candidateIdEvidence = collectRecommendNetworkCandidateIdEvidence(
+    networkBody,
+    profileBindingRoots
+  );
   if (!profile) {
     const encryptedPayload = parsedObjects.find((item) => (
       normalizeText(item?.zpData?.encryptGeekDetailInfo || item?.encryptGeekDetailInfo || "")
@@ -1234,7 +1477,9 @@ export function extractBossProfileFromNetworkBody(networkBody = {}) {
       zpData_keys: Object.keys(parsed?.zpData || {}).slice(0, 50),
       data_keys: Object.keys(parsed?.data || parsed?.zpData?.data || {}).slice(0, 50),
       encrypted_resume: Boolean(encryptedPayload),
-      encrypted_resume_length: normalizeText(encryptedPayload?.zpData?.encryptGeekDetailInfo || encryptedPayload?.encryptGeekDetailInfo || "").length
+      encrypted_resume_length: normalizeText(encryptedPayload?.zpData?.encryptGeekDetailInfo || encryptedPayload?.encryptGeekDetailInfo || "").length,
+      candidate_id_evidence: candidateIdEvidence,
+      response_candidate_id_diagnostics: responseCandidateIdDiagnostics
     };
   }
   return {
@@ -1243,6 +1488,8 @@ export function extractBossProfileFromNetworkBody(networkBody = {}) {
     status: networkBody.status ?? null,
     mimeType: networkBody.mimeType || null,
     text_length: text.length,
+    candidate_id_evidence: candidateIdEvidence,
+    response_candidate_id_diagnostics: responseCandidateIdDiagnostics,
     profile
   };
 }
@@ -1269,19 +1516,34 @@ export function buildScreeningCandidateFromDetail({
   source = "live-cdp-detail",
   metadata = {}
 } = {}) {
-  const parsedNetworkProfiles = networkBodies.map(extractBossProfileFromNetworkBody);
+  const normalizedDomain = normalizeDomain(domain);
+  const extractedNetworkProfiles = networkBodies.map(extractBossProfileFromNetworkBody);
+  const parsedNetworkProfiles = normalizedDomain === "recommend"
+    ? extractedNetworkProfiles.map((item) => bindRecommendNetworkProfileToCard(item, cardCandidate))
+    : extractedNetworkProfiles;
   const successfulProfiles = parsedNetworkProfiles.filter((item) => item.ok).map((item) => item.profile);
   const networkText = successfulProfiles.map((profile) => profile.text).filter(Boolean).join("\n\n");
   const networkIdentity = mergeCandidateProfiles(
     ...successfulProfiles.map((profile) => profile.identity)
   );
   const networkTags = unique(successfulProfiles.flatMap((profile) => profile.tags || []));
-  const combinedIdentity = mergeCandidateProfiles(
-    networkIdentity,
-    cardCandidate?.identity
-  );
+  const combinedIdentity = normalizedDomain === "recommend"
+    ? mergeCandidateProfiles(cardCandidate?.identity, networkIdentity)
+    : mergeCandidateProfiles(networkIdentity, cardCandidate?.identity);
+  const networkProfileBinding = normalizedDomain === "recommend"
+    ? {
+        required: true,
+        accepted_count: successfulProfiles.length,
+        rejected_count: parsedNetworkProfiles.filter((item) => (
+          item?.error === "RECOMMEND_NETWORK_PROFILE_CANDIDATE_BINDING_UNVERIFIED"
+        )).length,
+        profiles: parsedNetworkProfiles.map((item) => compactNetworkProfileCandidateBinding(
+          item?.candidate_binding
+        )).filter(Boolean)
+      }
+    : null;
   const candidate = normalizeCandidateProfile({
-    domain,
+    domain: normalizedDomain,
     source,
     id: cardCandidate?.id,
     href: cardCandidate?.links?.href,
@@ -1300,19 +1562,22 @@ export function buildScreeningCandidateFromDetail({
       ...metadata,
       card_candidate_source: cardCandidate?.source || null,
       network_profile_count: successfulProfiles.length,
+      network_profile_binding: networkProfileBinding,
       network_profiles: parsedNetworkProfiles.map((item) => ({
         ok: item.ok,
         url: item.url,
         status: item.status,
         error: item.error,
         text_length: item.text_length,
-        source_keys: item.profile?.source_keys || null
+        source_keys: item.profile?.source_keys || null,
+        candidate_binding: compactNetworkProfileCandidateBinding(item.candidate_binding)
       }))
     }
   });
   return {
     candidate,
-    parsed_network_profiles: parsedNetworkProfiles
+    parsed_network_profiles: parsedNetworkProfiles,
+    network_profile_binding: networkProfileBinding
   };
 }
 

package/src/domains/chat/action-journal.js

@@ -239,14 +239,31 @@ function appendRunId(runIds, runId) {
 
 const EVIDENCE_KEYS = new Set([
   "action",
+  "action_hit_test_attempt_count",
+  "action_hit_test_last_hit_backend_node_id",
+  "action_hit_test_reason",
   "active_candidate_id",
   "ask_error",
   "ask_ok",
   "confirm_confirmed",
   "confirm_error",
+  "control_backend_node_id",
+  "control_center_x",
+  "control_center_y",
+  "control_label",
+  "control_node_id",
+  "control_root_backend_node_id",
+  "control_root_node_id",
+  "control_rect_height",
+  "control_rect_width",
+  "control_rect_x",
+  "control_rect_y",
+  "control_root",
   "greeting_baseline_count",
   "greeting_evidence_readable",
   "message_observed",
+  "operation_id",
+  "pre_input_cdp_method",
   "request_confirmation_source",
   "request_ready_state_observed",
   "reason",
@@ -271,6 +288,37 @@ function sanitizeEvidence(value = {}) {
   return result;
 }
 
+function recordRevision(record) {
+  if (!record) return 0;
+  const historyLength = Array.isArray(record.history) ? record.history.length : 0;
+  const storedRevision = record.revision;
+  if (storedRevision == null) return historyLength;
+  const normalizedRevision = Number(storedRevision);
+  if (
+    !Number.isSafeInteger(normalizedRevision)
+    || normalizedRevision < 1
+    || normalizedRevision !== historyLength
+  ) {
+    throw journalError(
+      "CHAT_ACTION_JOURNAL_CORRUPT",
+      "Boss chat action journal revision does not exactly match its append-only history.",
+      {
+        stored_revision: storedRevision,
+        history_length: historyLength
+      }
+    );
+  }
+  return normalizedRevision;
+}
+
+function withRecordRevision(record) {
+  if (!record) return null;
+  return {
+    ...record,
+    revision: recordRevision(record)
+  };
+}
+
 export function hashChatActionGreeting(greeting) {
   const normalized = normalizeGreeting(greeting);
   if (!normalized) {
@@ -318,7 +366,7 @@ export function createChatActionJournal({
     const filePath = path.join(resolvedBaseDir, `${identity.actionKey}.json`);
     const stored = readJsonRecord(filePath);
     if (!stored) return null;
-    return cloneRecord(validateStoredRecord(stored, identity, filePath));
+    return cloneRecord(withRecordRevision(validateStoredRecord(stored, identity, filePath)));
   }
 
   function transition({
@@ -327,7 +375,10 @@ export function createChatActionJournal({
     state,
     runId = "",
     greeting,
-    evidence = {}
+    evidence = {},
+    recordIdempotent = false,
+    expectedUpdatedAt = null,
+    expectedRevision = null
   } = {}) {
     const identity = createChatActionIdentity({ scope, candidateId });
     const nextState = requireState(state);
@@ -337,7 +388,47 @@ export function createChatActionJournal({
     const lockHandle = acquireRecordLock(lockPath);
     try {
       const stored = readJsonRecord(filePath);
-      const existing = stored ? validateStoredRecord(stored, identity, filePath) : null;
+      const existing = stored
+        ? withRecordRevision(validateStoredRecord(stored, identity, filePath))
+        : null;
+      const observedRevision = recordRevision(existing);
+      if (expectedRevision != null) {
+        const normalizedExpectedRevision = Number(expectedRevision);
+        if (!Number.isSafeInteger(normalizedExpectedRevision) || normalizedExpectedRevision < 0) {
+          throw journalError(
+            "CHAT_ACTION_JOURNAL_REVISION_INVALID",
+            "Boss action journal expected revision must be a non-negative safe integer.",
+            { expected_revision: expectedRevision }
+          );
+        }
+        if (observedRevision !== normalizedExpectedRevision) {
+          throw journalError(
+            "CHAT_ACTION_JOURNAL_CONCURRENT_UPDATE",
+            "Boss action journal changed after it was read; this operation does not own the outbound action.",
+            {
+              action_key: identity.actionKey,
+              expected_revision: normalizedExpectedRevision,
+              observed_revision: observedRevision,
+              expected_updated_at: normalizeText(expectedUpdatedAt) || null,
+              observed_updated_at: normalizeText(existing?.updated_at) || null
+            }
+          );
+        }
+      }
+      if (
+        expectedUpdatedAt != null
+        && normalizeText(existing?.updated_at) !== normalizeText(expectedUpdatedAt)
+      ) {
+        throw journalError(
+          "CHAT_ACTION_JOURNAL_CONCURRENT_UPDATE",
+          "Boss action journal changed after it was read; this operation does not own the outbound action.",
+          {
+            action_key: identity.actionKey,
+            expected_updated_at: normalizeText(expectedUpdatedAt) || null,
+            observed_updated_at: normalizeText(existing?.updated_at) || null
+          }
+        );
+      }
       const suppliedGreeting = greeting == null ? "" : normalizeGreeting(greeting);
       const suppliedGreetingSha256 = suppliedGreeting ? hashChatActionGreeting(suppliedGreeting) : "";
 
@@ -369,7 +460,7 @@ export function createChatActionJournal({
           }
         );
       }
-      if (existing?.state === nextState) {
+      if (existing?.state === nextState && recordIdempotent !== true) {
         return {
           changed: false,
           idempotent: true,
@@ -384,6 +475,7 @@ export function createChatActionJournal({
       const record = existing ? {
         ...existing,
         state: nextState,
+        revision: observedRevision + 1,
         updated_at: at,
         evidence: {
           ...(existing.evidence && typeof existing.evidence === "object" ? existing.evidence : {}),
@@ -407,6 +499,7 @@ export function createChatActionJournal({
         scope_sha256: identity.scopeSha256,
         candidate_id: identity.candidateId,
         state: nextState,
+        revision: 1,
         greeting_sha256: suppliedGreetingSha256,
         evidence: safeEvidence,
         created_at: at,