trackly-cli 0.13.3 → 0.14.0

package/lib/apply-tab-set.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const APPLY_TAB_SET_FAILURE_CODES = Object.freeze({
+  CONTROLLER_INVENTORY_INCOMPLETE: 'controller_inventory_incomplete',
+  USER_INVENTORY_INCOMPLETE: 'user_inventory_incomplete',
+  EXPECTED_SET_EMPTY: 'expected_set_empty',
+  KEEP_SET_EMPTY_WITH_EXPECTED_TABS: 'keep_set_empty_with_expected_tabs',
+  DUPLICATE_EXPECTED_TAB_ID: 'duplicate_expected_tab_id',
+  DUPLICATE_KEEP_TAB_ID: 'duplicate_keep_tab_id',
+  DUPLICATE_CONTROLLER_TAB_ID: 'duplicate_controller_tab_id',
+  DUPLICATE_USER_TAB_ID: 'duplicate_user_tab_id',
+  AMBIGUOUS_CROSS_TYPE_TAB_ID: 'ambiguous_cross_type_tab_id',
+  EXPECTED_KEEP_CARDINALITY_MISMATCH: 'expected_keep_cardinality_mismatch',
+  EXPECTED_KEEP_SET_MISMATCH: 'expected_keep_set_mismatch',
+  EXPECTED_TAB_MISSING_FROM_INVENTORY_UNION: 'expected_tab_missing_from_inventory_union',
+});
+
+function canonicalizeTabId(tabId) {
+  if (typeof tabId === 'number') {
+    if (!Number.isSafeInteger(tabId)) throw new TypeError('Tab IDs supplied as numbers must be safe integers.');
+    return String(tabId);
+  }
+  if (typeof tabId !== 'string' || tabId.trim().length === 0) {
+    throw new TypeError('Tab IDs must be safe integers or nonblank opaque strings.');
+  }
+  if (tabId.length > 512) throw new RangeError('Opaque tab IDs must not exceed 512 characters.');
+  return tabId;
+}
+
+function canonicalizeTabIds(tabIds, { label, maxItems }) {
+  if (!Array.isArray(tabIds)) throw new TypeError('Tab ID collections must be arrays.');
+  if (tabIds.length > maxItems) {
+    throw new RangeError(`${label} must not contain more than ${maxItems} tab IDs.`);
+  }
+  return tabIds.map(canonicalizeTabId);
+}
+
+function hasDuplicates(tabIds) {
+  return new Set(tabIds).size !== tabIds.length;
+}
+
+function hasCrossTypeCollision(collections) {
+  const typesByCanonicalId = new Map();
+  for (const tabId of collections.flat()) {
+    const canonical = canonicalizeTabId(tabId);
+    const types = typesByCanonicalId.get(canonical) ?? new Set();
+    types.add(typeof tabId);
+    typesByCanonicalId.set(canonical, types);
+  }
+  return [...typesByCanonicalId.values()].some((types) => types.size > 1);
+}
+
+function sameSet(left, right) {
+  if (left.length !== right.length) return false;
+  const rightSet = new Set(right);
+  return left.every((tabId) => rightSet.has(tabId));
+}
+
+function validateApplyTabKeepSet({
+  expectedTabIds,
+  keepTabIds,
+  controllerInventory,
+  userInventory,
+}) {
+  const expected = canonicalizeTabIds(expectedTabIds, { label: 'expectedTabIds', maxItems: 100 });
+  const keep = canonicalizeTabIds(keepTabIds, { label: 'keepTabIds', maxItems: 100 });
+  const controller = canonicalizeTabIds(controllerInventory?.tabIds, {
+    label: 'controllerInventory.tabIds',
+    maxItems: 1000,
+  });
+  const user = canonicalizeTabIds(userInventory?.tabIds, {
+    label: 'userInventory.tabIds',
+    maxItems: 1000,
+  });
+  const failureCodes = [];
+  const addFailure = (code) => {
+    if (!failureCodes.includes(code)) failureCodes.push(code);
+  };
+
+  if (controllerInventory?.complete !== true) {
+    addFailure(APPLY_TAB_SET_FAILURE_CODES.CONTROLLER_INVENTORY_INCOMPLETE);
+  }
+  if (userInventory?.complete !== true) {
+    addFailure(APPLY_TAB_SET_FAILURE_CODES.USER_INVENTORY_INCOMPLETE);
+  }
+  if (expected.length === 0) addFailure(APPLY_TAB_SET_FAILURE_CODES.EXPECTED_SET_EMPTY);
+  if (expected.length > 0 && keep.length === 0) {
+    addFailure(APPLY_TAB_SET_FAILURE_CODES.KEEP_SET_EMPTY_WITH_EXPECTED_TABS);
+  }
+  if (hasDuplicates(expected)) addFailure(APPLY_TAB_SET_FAILURE_CODES.DUPLICATE_EXPECTED_TAB_ID);
+  if (hasDuplicates(keep)) addFailure(APPLY_TAB_SET_FAILURE_CODES.DUPLICATE_KEEP_TAB_ID);
+  if (hasDuplicates(controller)) addFailure(APPLY_TAB_SET_FAILURE_CODES.DUPLICATE_CONTROLLER_TAB_ID);
+  if (hasDuplicates(user)) addFailure(APPLY_TAB_SET_FAILURE_CODES.DUPLICATE_USER_TAB_ID);
+  if (hasCrossTypeCollision([
+    expectedTabIds, keepTabIds, controllerInventory.tabIds, userInventory.tabIds,
+  ])) addFailure(APPLY_TAB_SET_FAILURE_CODES.AMBIGUOUS_CROSS_TYPE_TAB_ID);
+  if (expected.length !== keep.length) {
+    addFailure(APPLY_TAB_SET_FAILURE_CODES.EXPECTED_KEEP_CARDINALITY_MISMATCH);
+  }
+  if (!sameSet(expected, keep)) addFailure(APPLY_TAB_SET_FAILURE_CODES.EXPECTED_KEEP_SET_MISMATCH);
+
+  const inventoryUnion = new Set([...controller, ...user]);
+  if (expected.some((tabId) => !inventoryUnion.has(tabId))) {
+    addFailure(APPLY_TAB_SET_FAILURE_CODES.EXPECTED_TAB_MISSING_FROM_INVENTORY_UNION);
+  }
+
+  const safeToFinalize = failureCodes.length === 0;
+  return {
+    safeToFinalize,
+    failureCodes,
+    expectedCount: expected.length,
+    keepCount: keep.length,
+    controllerInventoryCount: controller.length,
+    userInventoryCount: user.length,
+    inventoryUnionCount: inventoryUnion.size,
+    canonicalKeepTabIds: safeToFinalize ? keep : [],
+  };
+}
+
+module.exports = {
+  APPLY_TAB_SET_FAILURE_CODES,
+  canonicalizeTabId,
+  validateApplyTabKeepSet,
+};

package/lib/apply-upload.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const APPLY_CONTRACT = require('../contracts/trackly-apply-tools.json');
+
+const APPLY_UPLOAD_STAGES = Object.freeze([...APPLY_CONTRACT.constants.applyUploadStages]);
+const APPLY_UPLOAD_FAILURE_CODES = Object.freeze([
+  ...APPLY_CONTRACT.constants.applyUploadFailureCodes,
+]);
+const APPLY_UPLOAD_CAPABILITIES = Object.freeze([
+  'semanticControlDiscovery',
+  'chooserArming',
+  'fileAttachment',
+  'committedFilenameInspection',
+  'parserFieldRecheck',
+]);
+
+function validateApplyResumeUpload({ capabilities, events }) {
+  const failureCodes = [];
+  const seen = new Set();
+  let expectedIndex = 0;
+  let lastPassedStage = null;
+
+  for (const capability of APPLY_UPLOAD_CAPABILITIES) {
+    if (capabilities[capability] !== true) failureCodes.push('upload_capability_unavailable');
+  }
+
+  for (const event of events) {
+    if (seen.has(event.stage)) {
+      failureCodes.push('upload_stage_duplicate');
+      continue;
+    }
+    seen.add(event.stage);
+    const index = APPLY_UPLOAD_STAGES.indexOf(event.stage);
+    const isExpectedStage = index === expectedIndex;
+    if (!isExpectedStage) failureCodes.push('upload_stage_out_of_order');
+
+    const hasFailureCode = Boolean(event.failureCode);
+    if (hasFailureCode) {
+      failureCodes.push(event.failureCode);
+    }
+
+    if (event.outcome === 'failed' || hasFailureCode) {
+      if (!event.failureCode) failureCodes.push('upload_stage_missing');
+    } else if (isExpectedStage) {
+      expectedIndex += 1;
+      lastPassedStage = event.stage;
+    }
+  }
+
+  if (expectedIndex !== APPLY_UPLOAD_STAGES.length) failureCodes.push('upload_stage_missing');
+  const uniqueFailureCodes = [...new Set(failureCodes)];
+  return {
+    safeToClaimAttachment: uniqueFailureCodes.length === 0,
+    failureCodes: uniqueFailureCodes,
+    lastPassedStage,
+    completedStageCount: expectedIndex,
+    requiredStageCount: APPLY_UPLOAD_STAGES.length,
+  };
+}
+
+module.exports = {
+  APPLY_UPLOAD_CAPABILITIES,
+  APPLY_UPLOAD_FAILURE_CODES,
+  APPLY_UPLOAD_STAGES,
+  validateApplyResumeUpload,
+};

package/mcp/apply-tools.js

@@ -5,6 +5,12 @@ const { apiRequest } = require('../lib/client');
 const { prepareResume, verifyPreparedResume } = require('../lib/agent');
 const { lintApplicationText } = require('../lib/application-text');
 const { diagnoseLocalPath, ERRNO_PATTERN } = require('../lib/path-diagnostics');
+const { validateApplyTabKeepSet } = require('../lib/apply-tab-set');
+const {
+  APPLY_UPLOAD_FAILURE_CODES,
+  APPLY_UPLOAD_STAGES,
+  validateApplyResumeUpload,
+} = require('../lib/apply-upload');
 const { isIso3166Alpha2 } = require('../lib/iso-country-codes');
 const APPLY_CONTRACT = require('../contracts/trackly-apply-tools.json');
 
@@ -22,6 +28,8 @@ const APPLY_SURFACE_EVIDENCE_TYPES = APPLY_CONTRACT.constants.applySurfaceEviden
 const APPLY_SURFACE_OWNERSHIP_STATES = APPLY_CONTRACT.constants.applySurfaceOwnershipStates;
 const APPLY_SUBMISSION_EVIDENCE_TYPES = APPLY_CONTRACT.constants.applySubmissionEvidenceTypes;
 const APPLY_SUBMISSION_EVIDENCE_SOURCES = APPLY_CONTRACT.constants.applySubmissionEvidenceSources;
+const APPLY_EXECUTION_RECOVERY_ELIGIBILITY_CODES = APPLY_CONTRACT.constants.applyExecutionRecoveryEligibilityCodes;
+const APPLY_HANDOFF_RECONCILIATION_CLASSIFICATION_CODES = APPLY_CONTRACT.constants.applyHandoffReconciliationClassifications;
 const APPLY_BATCH_MAX_MEMBERS = 100;
 const APPLY_BATCH_MAX_CHECKPOINTS_PER_REQUEST = 20;
 const APPLY_BATCH_MAX_ACTIONS_PER_CHECKPOINT = 25;
@@ -32,6 +40,12 @@ const SAFE_IDEMPOTENCY_KEY = /^[\x20-\x7e]+$/;
 const iso3166Alpha2Schema = z.string().regex(/^[A-Za-z]{2}$/).refine(isIso3166Alpha2, {
   message: 'Expected an ISO 3166-1 alpha-2 country code',
 });
+const opaqueTabIdSchema = z.union([
+  z.number().int().safe(),
+  z.string().min(1).max(512).refine((value) => value.trim().length > 0, {
+    message: 'Expected a nonblank opaque tab ID',
+  }),
+]);
 const applyExecutionDispositionSchema = z.object({
   jobId: z.number().int().min(1),
   classification: z.enum(APPLY_EXECUTION_ACCESS_CLASSIFICATIONS),
@@ -44,6 +58,133 @@ const applyExecutionDispositionSchema = z.object({
   probeOnlyNoDraft: z.boolean().optional(),
   browserSurface: z.enum(APPLY_BROWSER_SURFACES),
 }).strict();
+const recoverableCandidateSchema = z.object({
+  candidateId: z.number().int().min(1),
+  jobId: z.number().int().min(1),
+  queuePosition: z.number().int().min(0),
+  eligibilityCode: z.enum(APPLY_EXECUTION_RECOVERY_ELIGIBILITY_CODES),
+}).strict();
+const recoverableExecutionSourceSchema = z.object({
+  sourceExecutionId: z.number().int().min(1),
+  sourceSnapshotHash: z.string().regex(/^[a-f0-9]{64}$/),
+  recoverableUntil: z.string().datetime(),
+  candidates: z.array(recoverableCandidateSchema).max(APPLY_EXECUTION_MAX_TARGET),
+}).strict().refine(({ candidates }) => (
+  new Set(candidates.map(({ candidateId }) => candidateId)).size === candidates.length
+), { message: 'recoverable source candidate IDs must be unique' });
+const recoverableExecutionsResponseSchema = z.object({
+  success: z.literal(true),
+  sources: z.array(recoverableExecutionSourceSchema).max(APPLY_EXECUTION_MAX_TARGET),
+}).strict().refine(({ sources }) => (
+  new Set(sources.map(({ sourceExecutionId }) => sourceExecutionId)).size === sources.length
+), { message: 'recoverable source execution IDs must be unique' });
+// Discovery responses are strict and value-free so unexpected fields never enter agent context.
+// Mutation responses permit additive top-level metadata, but keep safety-critical nested rows strict.
+const exactRecoveryResponseSchema = z.object({
+  success: z.literal(true),
+  replay: z.boolean(),
+  execution: z.object({
+    id: z.number().int().min(1),
+    mode: z.literal('recover_exact_members'),
+  }).passthrough(),
+  assertedCandidateIds: z.array(z.number().int().min(1)).max(APPLY_EXECUTION_MAX_TARGET),
+  eligibleCandidateIds: z.array(z.number().int().min(1)).max(APPLY_EXECUTION_MAX_TARGET),
+  eligibility: z.array(recoverableCandidateSchema).max(APPLY_EXECUTION_MAX_TARGET),
+}).passthrough();
+
+function validateExactRecoveryResponse(input, response) {
+  const requested = [...input.candidateIds].sort((a, b) => a - b);
+  const asserted = [...response.assertedCandidateIds].sort((a, b) => a - b);
+  const eligible = [...response.eligibleCandidateIds].sort((a, b) => a - b);
+  const eligibilityIds = response.eligibility
+    .map(({ candidateId }) => candidateId)
+    .sort((a, b) => a - b);
+  const matchesRequested = (values) => (
+    values.length === requested.length
+    && values.every((value, index) => value === requested[index])
+  );
+  if (
+    new Set(response.assertedCandidateIds).size !== response.assertedCandidateIds.length
+    || new Set(response.eligibleCandidateIds).size !== response.eligibleCandidateIds.length
+    || new Set(eligibilityIds).size !== eligibilityIds.length
+    || !matchesRequested(asserted)
+    || !matchesRequested(eligible)
+    || !matchesRequested(eligibilityIds)
+    || response.eligibility.some(({ eligibilityCode }) => eligibilityCode !== 'recoverable')
+  ) {
+    throw new Error('Exact recovery response does not match the requested candidate set.');
+  }
+  return response;
+}
+const handoffClaimMemberSchema = z.object({
+  memberId: z.number().int().min(1),
+  classification: z.enum(APPLY_HANDOFF_RECONCILIATION_CLASSIFICATION_CODES),
+}).strict();
+const handoffMemberSchema = z.object({
+  handoffId: z.number().int().min(1),
+  ordinal: z.number().int().min(0),
+  batchId: z.number().int().min(1),
+  memberId: z.number().int().min(1),
+  runId: z.number().int().min(1),
+  memberVersion: z.number().int().min(1),
+  inspectionEpoch: z.number().int().min(0),
+  reconciliationClassification: z.enum(APPLY_HANDOFF_RECONCILIATION_CLASSIFICATION_CODES).nullable(),
+  reconciliationResultStatus: z.string().max(100).nullable(),
+}).strict();
+const handoffListResponseSchema = z.object({
+  success: z.literal(true),
+  executionId: z.number().int().min(1),
+  handoffs: z.array(z.object({
+    id: z.number().int().min(1),
+    executionId: z.number().int().min(1),
+    orderedMemberSetHash: z.string().regex(/^[a-f0-9]{64}$/),
+    generation: z.number().int().min(1),
+    status: z.enum(['active', 'partially_reconciled']),
+    claimedAt: z.string().datetime().nullable(),
+    expiresAt: z.string().datetime(),
+    members: z.array(handoffMemberSchema).min(1).max(APPLY_EXECUTION_MAX_TARGET),
+  }).strict()).max(APPLY_EXECUTION_MAX_TARGET),
+}).strict();
+
+function validateHandoffListResponse(requestedExecutionId, response) {
+  const handoffIds = response.handoffs.map(({ id }) => id);
+  if (
+    response.executionId !== requestedExecutionId
+    || new Set(handoffIds).size !== handoffIds.length
+    || response.handoffs.some((handoff) => (
+      handoff.executionId !== requestedExecutionId
+      || new Set(handoff.members.map(({ memberId }) => memberId)).size !== handoff.members.length
+      || handoff.members.some((member) => member.handoffId !== handoff.id)
+    ))
+  ) {
+    throw new Error('Review handoff response does not match the requested execution and receipt bindings.');
+  }
+  return response;
+}
+const handoffClaimResponseSchema = z.object({
+  success: z.literal(true),
+  handoffId: z.number().int().min(1),
+  executionId: z.number().int().min(1),
+  orderedMemberSetHash: z.string().regex(/^[a-f0-9]{64}$/),
+  members: z.array(handoffClaimMemberSchema).min(1).max(APPLY_EXECUTION_MAX_TARGET),
+  transition: z.literal('claimed'),
+}).passthrough();
+
+function validateHandoffClaimResponse(request, response) {
+  const requestedMembers = request.members.map(({ memberId, classification }) => `${memberId}:${classification}`);
+  const returnedMembers = response.members.map(({ memberId, classification }) => `${memberId}:${classification}`);
+  if (
+    response.handoffId !== request.handoffId
+    || response.executionId !== request.executionId
+    || response.orderedMemberSetHash !== request.orderedMemberSetHash
+    || new Set(returnedMembers).size !== returnedMembers.length
+    || requestedMembers.length !== returnedMembers.length
+    || !requestedMembers.every((member) => returnedMembers.includes(member))
+  ) {
+    throw new Error('Handoff claim response does not match the requested handoff and member classifications.');
+  }
+  return response;
+}
 
 const truthCertificationCommon = {
   batchId: z.number().int().min(1),
@@ -121,7 +262,7 @@ const startApplyRunSchema = z.object({
   }
 });
 
-const APPLY_RELIABILITY_PROMPT = 'Protocol 3.5 / skill 4.4.2 reliability gate: only active=true identifies resumable execution work. A response with active=false and preserved=true is terminal read-only reconciliation evidence. Require nextAction=none and never fetch its compact snapshot, continue an unresolved wave, mutate a member, or interpret historical funnel counts as current work. For an active execution recovery or start, fetch one compact execution snapshot with only the current member IDs and profile keys required by the visible forms. Treat mutable and allowedOperations as authoritative. Never reopen or mutate authentication, account-creation, OTP, pre-form-CAPTCHA, or manual-only members. Only an explicit user request may call trackly_resume_parked_apply_member, and the returned member still requires a fresh non-mutating access probe. Use execution-scoped exact-resume content approval across unchanged replacement waves, but immediately verify the exact local path, hash, size, run binding, and expiration before every upload. Run trackly_lint_application_text before entering free text and fail closed on every violation or unsupported claim. Reconcile every newly supplied reusable answer to the canonical profile before review: save it, confirm it already matches, or report a schema gap. Never create app-shell tabs to reveal an already-bound browser tab without an exact focus receipt. Diagnose I/O errors only against the exact implicated path. Report the server funnel and durable milestone after every state change and at least once every 60 seconds during active work. Never click Submit.';
+const APPLY_RELIABILITY_PROMPT = 'Protocol 3.6 / skill 4.5.0 reliability gate: recover active work first. After full local context loss, list recoverable executions, show only stable job identity, obtain explicit confirmation of the exact candidate set, and call exact-member recovery without substitutions. Treat recovered tab presence, form state, and mutation authority as three separate facts; reacquire a fresh browser binding and inspection epoch before mutation. Before resolving broad submission statements, list active review handoffs for the execution; use only an explicit receipt or the sole returned active receipt, classify every member as detected, user_confirmed, unresolved, or contradictory, and claim that exact handoff before writing outcomes. Use provider-specific positive success evidence; an unchanged URL or title is never negative evidence. Validate an exact expected browser keep set locally before finalization. For resume uploads, negotiate the browser surface capabilities, identify the semantic control, arm the chooser before clicking, attach the immediately verified file, prove the user-facing filename committed, and recheck parser-modified fields. Use compact snapshots and server-provided mutability. Preserve user-edited and unknown non-empty fields. Never reopen parked work without explicit user resumption. Never click Submit.';
 
 function registerApplyTools(
   server,
@@ -143,6 +284,8 @@ function registerApplyTools(
       idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined,
     )
   );
+  const discoveredHandoffBindings = new Map();
+  const discoveredHandoffIdsByExecution = new Map();
   server.tool(
     'trackly_get_apply_queue',
     'Get the deterministic queue of jobs the user already approved by saving as check later. Do not rescore or veto these jobs.',
@@ -271,6 +414,101 @@ function registerApplyTools(
     ), 'Failed to fetch apply execution')
   );
 
+  server.tool(
+    'trackly_list_recoverable_apply_executions',
+    'List bounded, value-free exact-member recovery candidates after local context loss. Show the stable job identities to the user and obtain explicit confirmation before recovery; never infer or substitute candidates.',
+    {},
+    wrapTool(async () => recoverableExecutionsResponseSchema.parse(await applyControlRequest(
+      'GET', '/api/jobscout/apply/executions/recoverable',
+    )), 'Failed to list recoverable apply executions')
+  );
+
+  server.tool(
+    'trackly_recover_exact_apply_members',
+    'Create an exact-member recovery execution from one confirmed source snapshot. The asserted candidate set is immutable and replacements are forbidden.',
+    {
+      sourceExecutionId: z.number().int().min(1),
+      sourceSnapshotHash: z.string().regex(/^[a-f0-9]{64}$/),
+      candidateIds: z.array(z.number().int().min(1)).min(1).max(APPLY_EXECUTION_MAX_TARGET)
+        .refine((values) => new Set(values).size === values.length, {
+          message: 'candidateIds must be unique',
+        }),
+      explicitExactSetConfirmation: z.literal(true),
+      idempotencyKey: z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY),
+    },
+    wrapTool(async ({ idempotencyKey, ...input }) => validateExactRecoveryResponse(
+      input,
+      exactRecoveryResponseSchema.parse(await applyControlRequest('POST', '/api/jobscout/apply/executions/recover', {
+        mode: 'recover_exact_members',
+        ...input,
+      }, idempotencyKey)),
+    ), 'Failed to recover exact apply members')
+  );
+
+  server.tool(
+    'trackly_list_apply_review_handoffs',
+    'List active, nonexpired review-handoff receipts for one execution after context loss. Returns only stable IDs, lifecycle metadata, and member bindings; never browser values, URLs, or local paths.',
+    { executionId: z.number().int().min(1) },
+    wrapTool(async ({ executionId }) => {
+      const response = validateHandoffListResponse(
+        executionId,
+        handoffListResponseSchema.parse(await applyControlRequest(
+        'GET', `/api/jobscout/apply/executions/${executionId}/review-handoffs`,
+        )),
+      );
+      for (const handoffId of discoveredHandoffIdsByExecution.get(executionId) || []) {
+        discoveredHandoffBindings.delete(handoffId);
+      }
+      const discoveredHandoffIds = new Set();
+      for (const handoff of response.handoffs) {
+        discoveredHandoffBindings.set(handoff.id, {
+          executionId: handoff.executionId,
+          orderedMemberSetHash: handoff.orderedMemberSetHash,
+          memberIds: handoff.members.map(({ memberId }) => memberId),
+        });
+        discoveredHandoffIds.add(handoff.id);
+      }
+      discoveredHandoffIdsByExecution.set(executionId, discoveredHandoffIds);
+      return response;
+    }, 'Failed to list apply review handoffs')
+  );
+
+  server.tool(
+    'trackly_claim_apply_review_handoff',
+    'Claim one exact, unambiguous review-handoff group and classify every member before grouped submission reconciliation. Never use this tool to infer submission or replace success-page evidence or explicit user confirmation.',
+    {
+      handoffId: z.number().int().min(1),
+      members: z.array(z.object({
+        memberId: z.number().int().min(1),
+        classification: z.enum(APPLY_HANDOFF_RECONCILIATION_CLASSIFICATION_CODES),
+      }).strict()).min(1).max(APPLY_EXECUTION_MAX_TARGET)
+        .refine((values) => new Set(values.map(({ memberId }) => memberId)).size === values.length, {
+          message: 'members must contain unique memberId values',
+        }),
+      idempotencyKey: z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY),
+    },
+    wrapTool(async ({ handoffId, idempotencyKey, members }) => {
+      const binding = discoveredHandoffBindings.get(handoffId);
+      if (!binding) {
+        throw new Error('Review handoff must be selected from the latest discovery response.');
+      }
+      const { memberIds, ...receiptBinding } = binding;
+      const requestedMemberIds = new Set(members.map(({ memberId }) => memberId));
+      if (
+        requestedMemberIds.size !== memberIds.length
+        || memberIds.some((memberId) => !requestedMemberIds.has(memberId))
+      ) {
+        throw new Error('Handoff claim must classify every discovered member exactly once.');
+      }
+      return validateHandoffClaimResponse(
+        { handoffId, members, ...receiptBinding },
+        handoffClaimResponseSchema.parse(await applyControlRequest(
+        'POST', `/api/jobscout/apply/review-handoffs/${handoffId}/claim`, { members }, idempotencyKey,
+        )),
+      );
+    }, 'Failed to claim apply review handoff')
+  );
+
   server.tool(
     'trackly_get_apply_execution_snapshot',
     'Fetch a compact, bounded projection for one Apply execution. Request only the current members and profile keys needed for the visible form. The response owns mutability, allowed operations, milestones, lease timing, and progress.',
@@ -757,6 +995,7 @@ function registerApplyTools(
     'Record review readiness or a user-confirmed outcome. Before handoff use literal outcome=review_ready and verify awaiting_manual_submit. Mark submitted with literal outcome=submitted only after a success page or explicit user confirmation.',
     {
       runId: z.number().int().min(1),
+      idempotencyKey: z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY),
       batchId: z.number().int().min(1).optional(),
       memberId: z.number().int().min(1).optional(),
       inspectionEpoch: z.number().int().min(0).optional(),
@@ -764,13 +1003,19 @@ function registerApplyTools(
       outcome: z.enum(['review_ready', 'submitted', 'failed', 'blocked']),
       confirmation: z.enum(['user_confirmation', 'success_page']).optional(),
     },
-    wrapTool(async ({ runId, ...body }) => apiRequest('POST', `/api/jobscout/apply/runs/${runId}/outcome`, body, false, false, MCP_USER_AGENT), 'Failed to record application outcome')
+    wrapTool(async ({ runId, idempotencyKey, ...body }) => applyControlRequest(
+      'POST',
+      `/api/jobscout/apply/runs/${runId}/outcome`,
+      body,
+      idempotencyKey
+    ), 'Failed to record application outcome')
   );
 
   server.tool(
     'trackly_record_application_outcomes',
     'Bulk-record up to 20 leased, batch-bound review or user-confirmed outcomes. Before handoff every item uses literal outcome=review_ready and every recorded run must return awaiting_manual_submit. After manual confirmation use literal outcome=submitted. Each member returns recorded or a stable conflict without hiding sibling results.',
     {
+      idempotencyKey: z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY),
       outcomes: z.array(z.object({
         runId: z.number().int().min(1),
         batchId: z.number().int().min(1),
@@ -779,16 +1024,17 @@ function registerApplyTools(
         leaseToken: z.string().min(1).max(1024),
         outcome: z.enum(['review_ready', 'submitted', 'failed', 'blocked']),
         confirmation: z.enum(['user_confirmation', 'success_page']).optional(),
-      })).min(1).max(APPLY_BATCH_MAX_BULK_MUTATIONS),
+      })).min(1).max(APPLY_BATCH_MAX_BULK_MUTATIONS).refine(
+        (values) => new Set(values.map(({ runId }) => runId)).size === values.length,
+        { message: 'outcomes must contain unique runId values' }
+      ),
     },
     wrapTool(
-      async (params) => apiRequest(
+      async ({ idempotencyKey, ...params }) => applyControlRequest(
         'POST',
         '/api/jobscout/apply/outcomes/bulk',
         params,
-        false,
-        false,
-        MCP_USER_AGENT
+        idempotencyKey
       ),
       'Failed to record bulk application outcomes'
     )
@@ -835,6 +1081,44 @@ function registerApplyTools(
     wrapTool(async ({ exactPath, originalErrno }) => diagnoseLocalPath(exactPath, { originalErrno }), 'Local path diagnosis failed')
   );
 
+  server.tool(
+    'trackly_validate_apply_tab_keep_set',
+    'Locally validate a caller-supplied session-finalizer keep set against complete controller and user tab inventories. This pure helper never enumerates, focuses, closes, hands off, or finalizes browser tabs and never sends tab IDs to Trackly.',
+    {
+      expectedTabIds: z.array(opaqueTabIdSchema).min(1).max(100),
+      keepTabIds: z.array(opaqueTabIdSchema).max(100),
+      controllerInventory: z.object({
+        complete: z.boolean(),
+        tabIds: z.array(opaqueTabIdSchema).max(1000),
+      }).strict(),
+      userInventory: z.object({
+        complete: z.boolean(),
+        tabIds: z.array(opaqueTabIdSchema).max(1000),
+      }).strict(),
+    },
+    wrapTool(async (params) => validateApplyTabKeepSet(params), 'Apply tab keep-set validation failed')
+  );
+
+  server.tool(
+    'trackly_validate_apply_resume_upload',
+    'Locally validate the browser adapter capabilities and ordered, value-free proof stages required to claim one resume attachment. This helper does not open a chooser, read a local path, control the browser, or send values to Trackly.',
+    {
+      capabilities: z.object({
+        semanticControlDiscovery: z.boolean(),
+        chooserArming: z.boolean(),
+        fileAttachment: z.boolean(),
+        committedFilenameInspection: z.boolean(),
+        parserFieldRecheck: z.boolean(),
+      }).strict(),
+      events: z.array(z.object({
+        stage: z.enum(APPLY_UPLOAD_STAGES),
+        outcome: z.enum(['passed', 'failed']),
+        failureCode: z.enum(APPLY_UPLOAD_FAILURE_CODES).optional(),
+      }).strict()).max(APPLY_UPLOAD_STAGES.length),
+    },
+    wrapTool(async (params) => validateApplyResumeUpload(params), 'Apply resume upload validation failed')
+  );
+
   server.tool(
     'trackly_verify_prepared_resume',
     'Immediately before attachment, recompute the prepared resume fingerprint, validate its run and expiration, and lock the confirmed file read-only.',
@@ -857,11 +1141,20 @@ function registerApplyTools(
     messages: [{
       role: 'user',
       content: { type: 'text', text: APPLY_RELIABILITY_PROMPT },
+    }, {
+      role: 'user',
+      content: { type: 'text', text: 'Only active=true identifies resumable execution work. Active=false and preserved=true is terminal read-only reconciliation evidence.' },
+    }, {
+      role: 'user',
+      content: {
+        type: 'text',
+        text: 'Protocol 3.6.0 reliability gate for new work: require MCP contract 3.7.1 and skill 4.5.0. After complete local context loss, list bounded recovery candidates, obtain explicit confirmation of the exact set, and recover only that set. Treat tab recovery, form-state recovery, and mutation authority as independent. List active handoff receipts for the execution before resolving grouped submission statements; use the named receipt or the sole returned active receipt, classify every member, and claim that receipt before recording outcomes. Validate tab keep sets and resume upload stages locally. Never send raw browser values or click Submit.',
+      },
     }, {
       role: 'user',
       content: {
         type: 'text',
-        text: 'Protocol 3.5.0 reliability gate: require the fetched compatibleSkillMinimumVersion or newer for new execution work. Read the Apply protocol first. Only protocol 3.5 or newer with the compact-snapshot capability may call trackly_get_apply_execution_snapshot or the parked-member resume and execution-resume approval tools. An already-active protocol 3.4 execution is read-only legacy recovery: use only its published get or stop tools and never mutate its browser forms. Only when the fetched protocol is 3.4 or newer call trackly_get_active_apply_execution before legacy batch recovery, including when accessible execution is disabled. For protocol 3.3, skip the execution endpoint and recover the already-active immutable fixed batch directly; protocol 3.2 remains valid only for an already-active explicit legacy single run. A disabled rollout may preserve an active execution: recover it read-only and use only get or stop tools until the capability is enabled; never start, advance, or record dispositions while disabled. If disabled and no execution is active, use the legacy fixed-batch path. Recover every entry in execution.unresolvedWaves in ascending waveOrder; an older unresolved wave remains part of recovery after a replacement wave exists, and execution.currentWave is only the latest scheduling identity, never the complete recovery set. For “fill/apply to the next N,” recover or start one complete_next_n_accessible execution with target 1–20 and follow only the server nextAction and authoritative funnel. If the requested N differs from the active target, explain the mismatch, obtain explicit confirmation, stop the old execution with reason target_changed, refetch its terminal state, then start the new target. If an immutable fixed batch is active when the user requests complete_next_n_accessible, explain the incompatible mode and summarize any review-ready, submitted, or unresolved work before browser mutation. Resume that exact fixed batch when the user chooses to finish it. If the user instead says to start fresh, leave, replace, discard, or otherwise abandon the old batch, treat that statement as explicit cancellation confirmation: refetch the latest batch revision, call trackly_cancel_apply_batch with reason user_requested_restart and a fresh idempotency key, refetch until no active fixed batch remains, preserve every existing browser tab without mutation, and start the requested accessible execution in the same turn. Never wait for batch expiry and never create a scheduled continuation merely to escape an obsolete batch. If cancellation reports submission_in_progress, preserve everything and stop for the user; do not cancel or start replacement work. If the user asks to stop, call trackly_stop_apply_execution with reason user_requested and refetch its terminal state. Continue immutable child waves from the original recent-first snapshot until durablyReviewReady plus submitted reaches target, the queue is exhausted, or the user stops. Accessible drafts awaiting answers and forms currently being filled occupy target slots; authentication, account creation, OTP, pre-form CAPTCHA, exclusions, manual-only, conflicts, and revocations do not. Record only typed value-free live-probe dispositions. Advance only when no current-wave member remains unclassified queued or inspecting. Never calculate replacements or progress locally. For an explicit “inspect the next N records” request, use the existing fixed immutable batch and never replenish it; if a different accessible execution is active, confirm the intent change with the user, stop that execution with reason target_changed, refetch its terminal state, then recover or create the fixed batch. A cache hint may prioritize a live minimal non-mutating probe but never authorizes private-data entry or replaces that probe. After a redirect or contradictory observation, report only the fresh live disposition with its exact binding and let the backend invalidate its own hint. Preserve every user-edited or unknown non-empty field through the local provenance ledger. Never submit.',
+        text: 'Legacy protocol compatibility gate: require the fetched compatibleSkillMinimumVersion or newer for all new work and use protocol 3.6.0 as specified above. Read the Apply protocol first. Only protocol 3.5 or newer with the compact-snapshot capability may call trackly_get_apply_execution_snapshot or the parked-member resume and execution-resume approval tools. An already-active protocol 3.4 execution is read-only legacy recovery: use only its published get or stop tools and never mutate its browser forms. Only when the fetched protocol is 3.4 or newer call trackly_get_active_apply_execution before legacy batch recovery, including when accessible execution is disabled. For protocol 3.3, skip the execution endpoint and recover the already-active immutable fixed batch directly; protocol 3.2 remains valid only for an already-active explicit legacy single run. A disabled rollout may preserve an active execution: recover it read-only and use only get or stop tools until the capability is enabled; never start, advance, or record dispositions while disabled. If disabled and no execution is active, use the legacy fixed-batch path. Recover every entry in execution.unresolvedWaves in ascending waveOrder; an older unresolved wave remains part of recovery after a replacement wave exists, and execution.currentWave is only the latest scheduling identity, never the complete recovery set. For “fill/apply to the next N,” recover or start one complete_next_n_accessible execution with target 1–20 and follow only the server nextAction and authoritative funnel. If the requested N differs from the active target, explain the mismatch, obtain explicit confirmation, stop the old execution with reason target_changed, refetch its terminal state, then start the new target. If an immutable fixed batch is active when the user requests complete_next_n_accessible, explain the incompatible mode and summarize any review-ready, submitted, or unresolved work before browser mutation. Resume that exact fixed batch when the user chooses to finish it. If the user instead says to start fresh, leave, replace, discard, or otherwise abandon the old batch, treat that statement as explicit cancellation confirmation: refetch the latest batch revision, call trackly_cancel_apply_batch with reason user_requested_restart and a fresh idempotency key, refetch until no active fixed batch remains, preserve every existing browser tab without mutation, and start the requested accessible execution in the same turn. Never wait for batch expiry and never create a scheduled continuation merely to escape an obsolete batch. If cancellation reports submission_in_progress, preserve everything and stop for the user; do not cancel or start replacement work. If the user asks to stop, call trackly_stop_apply_execution with reason user_requested and refetch its terminal state. Continue immutable child waves from the original recent-first snapshot until the authoritative backend funnel says targetReached, the queue is exhausted, or the user stops. Treat achievementCount and target-capped completed as the cumulative target authority. durablyReviewReady and submitted are current operator projections only; never add them together locally to reconstruct completion. Accessible drafts awaiting answers and forms currently being filled occupy target slots; authentication, account creation, OTP, pre-form CAPTCHA, exclusions, manual-only, conflicts, and revocations do not. Record only typed value-free live-probe dispositions. Advance only when no current-wave member remains unclassified queued or inspecting. Never calculate replacements or progress locally. For an explicit “inspect the next N records” request, use the existing fixed immutable batch and never replenish it; if a different accessible execution is active, confirm the intent change with the user, stop that execution with reason target_changed, refetch its terminal state, then recover or create the fixed batch. A cache hint may prioritize a live minimal non-mutating probe but never authorizes private-data entry or replaces that probe. After a redirect or contradictory observation, report only the fresh live disposition with its exact binding and let the backend invalidate its own hint. Preserve every user-edited or unknown non-empty field through the local provenance ledger. Never submit.',
       },
     }, {
       role: 'user',