trackly-cli 0.13.4 → 0.14.1

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,9 @@ function registerApplyTools(
       idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined,
     )
   );
+  const discoveredRecoverableSources = new Map();
+  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 +415,121 @@ 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 () => {
+      const response = recoverableExecutionsResponseSchema.parse(await applyControlRequest(
+        'GET', '/api/jobscout/apply/executions/recoverable',
+      ));
+      discoveredRecoverableSources.clear();
+      for (const source of response.sources) {
+        discoveredRecoverableSources.set(source.sourceExecutionId, {
+          sourceSnapshotHash: source.sourceSnapshotHash,
+          candidateIds: new Set(source.candidates.map(({ candidateId }) => candidateId)),
+        });
+      }
+      return response;
+    }, '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 }) => {
+      const source = discoveredRecoverableSources.get(input.sourceExecutionId);
+      if (
+        !source
+        || source.sourceSnapshotHash !== input.sourceSnapshotHash
+        || input.candidateIds.some((candidateId) => !source.candidateIds.has(candidateId))
+      ) {
+        throw new Error('Exact recovery must use one source and candidate set from the latest discovery response.');
+      }
+      return 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 +1016,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 +1024,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 +1045,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 +1102,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 +1162,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',

package/mcp/server.js

@@ -7,6 +7,7 @@ const { z } = require('zod');
 const { apiRequest, createTracklyAccessError, hasAuth, maintenanceOutput } = require('../lib/client');
 const { version: PACKAGE_VERSION } = require('../package.json');
 const { registerApplyTools } = require('./apply-tools');
+const { configureMcpAnalytics, shutdownMcpAnalytics } = require('./analytics');
 
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
 const MCP_MAINTENANCE_ERROR_CODE = -32002;
@@ -15,6 +16,8 @@ const MCP_AUTH_ERROR_CODE = -32004;
 const AUTH_HINT =
   'Existing members: run `trackly login` or set TRACKLY_API_KEY. ' +
   'New members need a private invite during the limited rollout; request access at https://usetrackly.app/early-access.';
+const MCP_ANALYTICS_CONTEXT_DESCRIPTION =
+  'Briefly explain why this tool helps the current job-search goal. Never include resume text, profile answers, demographic or work-authorization answers, application notes, credentials, or secrets.';
 
 // Mirrors `granola-followup-app/src/services/region-classifier.ts:8` REGION_TAGS.
 // Keep in sync when the backend enum changes.
@@ -48,6 +51,22 @@ const JOB_MODALITIES = ['full_time', 'internship', 'all'];
 // workArrangements query contract and job_postings constraint.
 const WORK_ARRANGEMENTS = ['remote', 'hybrid', 'in_person', 'unspecified'];
 
+const MCP_MISSING_CAPABILITY_VALUES = [
+  'search', 'inspect', 'compare', 'rank', 'recommend', 'track', 'update', 'apply',
+  'submit', 'export', 'notify', 'schedule', 'integrate', 'authenticate', 'debug', 'other',
+];
+const MCP_MISSING_ACTION_VALUES = [
+  'find', 'read', 'compare', 'rank', 'create', 'update', 'delete', 'submit',
+  'export', 'notify', 'schedule', 'connect', 'debug', 'other',
+];
+const MCP_MISSING_RESOURCE_VALUES = [
+  'job', 'company', 'application', 'contact', 'profile', 'resume', 'preference',
+  'analytics', 'account', 'tool', 'other',
+];
+const MCP_MISSING_DESTINATION_VALUES = [
+  'trackly', 'external_site', 'file', 'email', 'calendar', 'crm', 'browser', 'other',
+];
+
 // `sort` enum matches backend handler at `jobscout.ts:3053` — NOT the pre-fix
 // `newest|oldest|company` (backend rejects oldest/company with HTTP 400).
 const SORT_VALUES = ['newest', 'match'];
@@ -169,7 +188,7 @@ function throwMcpResourceError(error) {
 }
 
 function wrapTool(handler, fallbackMessage) {
-  return async (params) => {
+  return async (params, extra) => {
     try {
       if (!hasAuth()) {
         return createAuthErrorResult();
@@ -180,6 +199,11 @@ function wrapTool(handler, fallbackMessage) {
         content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
       };
     } catch (error) {
+      if (extra && typeof extra === 'object') {
+        extra.__mcp_analytics_error = error instanceof Error
+          ? error
+          : new Error(error?.message || fallbackMessage, { cause: error });
+      }
       return createErrorResult(
         error,
         fallbackMessage,
@@ -485,28 +509,119 @@ function createServer() {
     mcpUserAgent: MCP_USER_AGENT,
     throwMcpResourceError,
   });
+
+  server.tool(
+    'get_more_tools',
+    'Report a capability Trackly does not currently provide. Use structured categories; context is optional and is classified but never stored as raw text.',
+    {
+      requestedCapability: z.enum(MCP_MISSING_CAPABILITY_VALUES).optional(),
+      requestedAction: z.enum(MCP_MISSING_ACTION_VALUES).optional(),
+      requestedResource: z.enum(MCP_MISSING_RESOURCE_VALUES).optional(),
+      requestedDestination: z.enum(MCP_MISSING_DESTINATION_VALUES).optional(),
+      context: z.string().optional().describe(MCP_ANALYTICS_CONTEXT_DESCRIPTION),
+    },
+    async () => ({
+      content: [{
+        type: 'text',
+        text: JSON.stringify({ accepted: true, delivery: 'best_effort' }),
+      }],
+    }),
+  );
+
   return server;
 }
 
-async function startMcpServer() {
+// Keep `createServer` a deterministic catalog factory for embedders and
+// contract verification. Analytics belongs at the executable startup boundary,
+// after every source tool has been registered.
+function configureServerAnalytics(server, options = {}) {
+  if (typeof options.configureAnalytics === 'function') {
+    return options.configureAnalytics(server, options.analytics);
+  }
+  return configureMcpAnalytics(server, options.analytics);
+}
+
+async function startMcpServer(options = {}) {
   const server = createServer();
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  configureServerAnalytics(server, options);
+  const transport = options.transport || new StdioServerTransport();
+  const shutdownAnalytics = options.shutdownAnalytics || shutdownMcpAnalytics;
+  const previousOnClose = server.server.onclose;
+  const beginAnalyticsShutdown = () => {
+    try {
+      Promise.resolve(shutdownAnalytics(server)).catch(() => {});
+    } catch {
+      // Analytics teardown must not affect transport teardown.
+    }
+  };
+  server.server.onclose = () => {
+    try {
+      previousOnClose?.();
+    } catch {
+      // Preserve fail-open behavior if an instrumentation callback misbehaves.
+    }
+    beginAnalyticsShutdown();
+  };
+
+  try {
+    await server.connect(transport);
+  } catch (error) {
+    try {
+      await shutdownAnalytics(server);
+    } catch {
+      // Preserve the original transport failure.
+    }
+    throw error;
+  }
   return server;
 }
 
+function installMcpSignalHandlers(server, options = {}) {
+  const signalTarget = options.signalTarget || process;
+  const exit = options.exit || ((code) => process.exit(code));
+  const shutdownAnalytics = options.shutdownAnalytics || shutdownMcpAnalytics;
+  let terminating = false;
+  const handlers = new Map();
+  const cleanup = () => {
+    for (const [signal, handler] of handlers) {
+      signalTarget.removeListener(signal, handler);
+    }
+    handlers.clear();
+  };
+  for (const [signal, exitCode] of [['SIGINT', 130], ['SIGTERM', 143]]) {
+    const handler = () => {
+      if (terminating) return;
+      terminating = true;
+      void Promise.resolve()
+        .then(() => shutdownAnalytics(server))
+        .catch(() => {})
+        .finally(() => {
+          cleanup();
+          exit(exitCode);
+        });
+    };
+    handlers.set(signal, handler);
+    signalTarget.on(signal, handler);
+  }
+  return cleanup;
+}
+
 if (require.main === module) {
-  startMcpServer().catch((error) => {
-    console.error('MCP server error:', error);
-    process.exit(1);
-  });
+  startMcpServer()
+    .then((server) => installMcpSignalHandlers(server))
+    .catch((error) => {
+      console.error('MCP server error:', error);
+      process.exit(1);
+    });
 }
 
 module.exports = {
   AUTH_HINT,
   createAuthErrorResult,
   createErrorResult,
+  configureServerAnalytics,
   createServer,
+  installMcpSignalHandlers,
   startMcpServer,
   throwMcpResourceError,
 };