trackly-cli 0.7.3 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 [![npm](https://img.shields.io/npm/v/trackly-cli.svg)](https://www.npmjs.com/package/trackly-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node 18+](https://img.shields.io/badge/node-18+-brightgreen.svg)](https://nodejs.org/)
+[![Node 20+](https://img.shields.io/badge/node-20+-brightgreen.svg)](https://nodejs.org/)
 [![MCP Server](https://img.shields.io/badge/MCP-Server-blue.svg)](https://modelcontextprotocol.io/)
 
 # trackly-cli
@@ -31,11 +31,11 @@ trackly login
 trackly jobs --function product
 ```
 
-> **Prerequisites:** [Node.js 18+](https://nodejs.org/) (LTS recommended). On macOS with the official `.pkg` installer, global npm installs may require `sudo`.
+> **Prerequisites:** [Node.js 20+](https://nodejs.org/) (LTS recommended). On macOS with the official `.pkg` installer, global npm installs may require `sudo`.
 
 ## At a Glance
 
-1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 24 local MCP tools
+1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 36 local MCP tools
 
 ## CLI Commands
 
@@ -177,11 +177,23 @@ Then use natural language in any of these clients:
 | trackly_get_application_profile | Get versioned profile answers and provenance |
 | trackly_get_profile_onboarding | Get schema plus missing questions |
 | trackly_update_application_profile | Save scoped answers with optimistic concurrency |
-| trackly_start_apply_run | Start a manual-submit browser run |
+| trackly_create_apply_batch | Freeze an exact recent-first approved batch |
+| trackly_get_active_apply_batch | Recover the newest unexpired active batch after context loss |
+| trackly_get_apply_batch | Read frozen membership with opaque pagination |
+| trackly_claim_apply_batch | Acquire or renew a batch mutation lease |
+| trackly_checkpoint_apply_batch | Bulk-record redacted inspection checkpoints and human actions |
+| trackly_bind_apply_surface | Bind an initial or recovered browser surface to the existing run and exact requisition URL |
+| trackly_record_apply_surface_evidence | Record current-epoch inventory, missing-tab, close-receipt, and post-close absence evidence |
+| trackly_record_apply_submission_evidence | Record redacted submit-request, success-page, user-confirmation, or provider-receipt evidence |
+| trackly_approve_apply_batch_resume | Approve one exact default resume for the current frozen run set |
+| trackly_certify_apply_batch_truth | Certify final answer and wording fingerprints after every other review-readiness gate |
+| trackly_start_apply_run | Start or reuse a manual-submit browser run |
 | trackly_get_apply_evidence | Get aggregate, value-free beta evidence and release readiness |
 | trackly_get_apply_protocol | Get current workflow and compatibility rules |
 | trackly_report_apply_observation | Send redacted ATS mechanics feedback |
+| trackly_report_apply_observations | Bulk-send up to 20 leased, batch-bound redacted observations |
 | trackly_record_application_outcome | Record review or confirmed submission outcome |
+| trackly_record_application_outcomes | Bulk-record up to 20 leased batch outcomes with per-member conflicts |
 | trackly_prepare_resume | Prepare a private expiring resume file for upload |
 | trackly_verify_prepared_resume | Recheck the confirmed resume immediately before attachment |
 
@@ -249,7 +261,7 @@ trackly config --base-url http://127.0.0.1:3000  # Point at a different backend
 | Job search + filters | Yes | Yes | Yes |
 | Apply/save/dismiss | Yes | Yes | Yes |
 | AI-powered search | Yes (trackly ask) | Yes | Yes |
-| MCP integration | Yes (20 local tools) | -- | -- |
+| MCP integration | Yes (36 local tools) | -- | -- |
 | Browser required | No | Yes | No |
 | Best for | Terminal + AI agents | Visual browsing | Custom integrations |
 
@@ -263,7 +275,7 @@ Install trackly-cli (`npm install -g trackly-cli`), authenticate with `trackly l
 
 **What MCP servers exist for job searching?**
 
-trackly-cli includes a built-in MCP server with 24 tools for job search, company lookup, discovery preferences, application tracking, profile onboarding, beta evidence, and manual-submit form preparation. Run `trackly mcp` or use `trackly agent setup --client claude`.
+trackly-cli includes a built-in MCP server with 36 tools for job search, company lookup, discovery preferences, application tracking, frozen-batch orchestration, profile onboarding, beta evidence, and manual-submit form preparation. Run `trackly mcp` or use `trackly agent setup --client claude`.
 
 **How do I use Claude Code for job hunting?**
 

package/bin/trackly

@@ -1159,6 +1159,8 @@ async function cmdAgent(args) {
     console.log(color('bold', 'Trackly Apply doctor'));
     console.log(`Overall: ${color(report.ok ? 'green' : 'yellow', report.ok ? 'ready' : 'needs attention')}`);
     console.log(`Authenticated: ${report.authenticated ? 'yes' : 'no'}`);
+    console.log(`CLI: ${report.cliVersion}; MCP contract: ${report.mcpContractVersion}`);
+    console.log(`Skill: ${report.skillVersion}; digest: ${report.skillPackIntegrity.expectedDigest || 'unavailable'}`);
     console.log(`Protocol: ${report.protocol?.version || 'unavailable'}; compatible=${report.compatible ? 'yes' : 'no'}`);
     console.log(`Semantic browser + computer use: ${report.browserControl.semanticReady ? 'ready' : 'not verified'}`);
     for (const client of report.clients) {

package/contracts/trackly-apply-tools.json

@@ -1,22 +1,41 @@
 {
-  "contractVersion": "3.2.0",
+  "contractVersion": "3.3.1",
   "constants": {
     "applyScenarioCodes": ["browser_reclaim", "resume_upload", "resume_parser_recheck", "semantic_boolean_commit", "custom_select_commit", "multi_step_navigation", "free_text_voice", "required_error_sweep", "final_consent", "handoff_reclaim", "critical_contact_integrity", "manual_submit_boundary", "job_identity_match"],
-    "applyBrowserSurfaces": ["codex_in_app", "chrome_extension", "claude_in_chrome"]
+    "applyBrowserSurfaces": ["codex_in_app", "chrome_extension", "claude_in_chrome"],
+    "applyCheckpointActionCodes": ["answer/unknown", "auth/sign_in", "auth/otp", "captcha/before_form", "captcha/at_submit", "artifact/upload_required", "legal/decision_required", "consent/decision_required", "review/manual_submit", "trust/origin_mismatch", "observability/unverifiable_state"],
+    "applyCheckpointPacketPhases": ["first_pass", "delta"],
+    "applySurfaceBindingReasons": ["initial_binding", "recovery_binding"],
+    "applySurfaceEvidenceTypes": ["surface_inventory_reconciled", "surface_missing", "surface_close_attempted", "surface_close_receipt", "surface_post_close_absent", "surface_close_failed"],
+    "applySurfaceOwnershipStates": ["controller_owned", "user_owned", "controller_user_union", "unresolved"],
+    "applySubmissionEvidenceTypes": ["request_accepted", "confirmation_detected", "provider_receipt_detected"],
+    "applySubmissionEvidenceSources": ["submission_request", "success_page", "user_confirmation", "provider_receipt", "post_submit_receipt"]
   },
   "tools": {
-    "trackly_get_apply_queue": "{limit:z.number().int().min(1).max(100).optional()}",
+    "trackly_get_apply_queue": "{limit:z.number().int().min(1).max(100).optional(),cursor:z.string().min(1).max(2048).optional()}",
     "trackly_get_application_profile": "{includeSensitive:z.boolean().optional(),provider:z.string().max(100).optional(),companyId:z.string().max(100).optional()}",
     "trackly_get_profile_onboarding": "{}",
     "trackly_update_application_profile": "{expectedRevision:z.number().int().min(1),source:z.enum(['web','ios','macos','codex','claude','mcp']).optional(),changes:z.array(z.discriminatedUnion('scope',[z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('global'),questionLabel:z.string().max(1000).optional()}),z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('provider'),scopeValue:z.string().min(1).max(200),questionLabel:z.string().max(1000).optional()}),z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('company'),scopeValue:z.string().min(1).max(200),questionLabel:z.string().max(1000).optional()})])).max(100).optional(),education:z.array(z.object({school:z.string().min(1).max(500),degree:z.string().max(500).nullable().optional(),fieldOfStudy:z.string().max(500).nullable().optional(),gpa:z.string().max(50).nullable().optional(),startDate:z.string().max(50).nullable().optional(),endDate:z.string().max(50).nullable().optional()})).max(20).optional(),confirmProfile:z.boolean().optional(),sensitiveStorageConsent:z.boolean().optional()}",
-    "trackly_start_apply_run": "{jobId:z.number().int().min(1),clientName:z.string().max(100).optional()}",
+    "trackly_create_apply_batch": "{limit:z.number().int().min(1).max(100),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_get_active_apply_batch": "{limit:z.number().int().min(1).max(APPLY_BATCH_MAX_MEMBERS).optional(),cursor:z.string().min(1).max(2048).optional(),actionLimit:z.number().int().min(1).max(APPLY_BATCH_MAX_MEMBERS).optional(),actionCursor:z.string().min(1).max(2048).optional()}",
+    "trackly_get_apply_batch": "{batchId:z.number().int().min(1),limit:z.number().int().min(1).max(APPLY_BATCH_MAX_MEMBERS).optional(),cursor:z.string().min(1).max(2048).optional(),actionLimit:z.number().int().min(1).max(APPLY_BATCH_MAX_MEMBERS).optional(),actionCursor:z.string().min(1).max(2048).optional()}",
+    "trackly_claim_apply_batch": "{batchId:z.number().int().min(1),expectedRevision:z.number().int().min(1),leaseOwner:z.string().min(1).max(1024),leaseToken:z.string().min(1).max(1024),leaseDurationMs:z.number().int().min(15000).max(300000)}",
+    "trackly_checkpoint_apply_batch": "{batchId:z.number().int().min(1),leaseToken:z.string().min(1).max(1024),checkpoints:z.array(z.object({memberId:z.number().int().min(1),runId:z.number().int().min(1),expectedMemberVersion:z.number().int().min(1),expectedInspectionEpoch:z.number().int().min(0),inspectionEpoch:z.number().int().min(0),packetPhase:z.enum(APPLY_CHECKPOINT_PACKET_PHASES).optional(),knownFieldsCommitted:z.boolean(),resolvedActionIds:z.array(z.string().regex(/^[1-9][0-9]*$/)).max(APPLY_BATCH_MAX_ACTIONS_PER_CHECKPOINT).optional(),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY),actions:z.array(z.object({actionCode:z.enum(APPLY_CHECKPOINT_ACTION_CODES),continuationAllowed:z.boolean(),fieldFingerprint:z.string().regex(/^[a-f0-9]{64}$/).optional()})).min(1).max(APPLY_BATCH_MAX_ACTIONS_PER_CHECKPOINT)})).min(1).max(APPLY_BATCH_MAX_CHECKPOINTS_PER_REQUEST)}",
+    "trackly_bind_apply_surface": "{batchId:z.number().int().min(1),memberId:z.number().int().min(1),runId:z.number().int().min(1),expectedMemberVersion:z.number().int().min(1),expectedInspectionEpoch:z.number().int().min(0),leaseToken:z.string().min(1).max(1024),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/),browserSurface:z.enum(APPLY_BROWSER_SURFACES),adapterCode:z.string().regex(SAFE_OBSERVATION_CODE),bindingReason:z.enum(APPLY_SURFACE_BINDING_REASONS),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_record_apply_surface_evidence": "{batchId:z.number().int().min(1),memberId:z.number().int().min(1),runId:z.number().int().min(1),expectedMemberVersion:z.number().int().min(1),expectedInspectionEpoch:z.number().int().min(1),leaseToken:z.string().min(1).max(1024),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/),browserSurface:z.enum(APPLY_BROWSER_SURFACES),adapterCode:z.string().regex(SAFE_OBSERVATION_CODE),ownershipState:z.enum(APPLY_SURFACE_OWNERSHIP_STATES),completeInventory:z.boolean(),evidenceType:z.enum(APPLY_SURFACE_EVIDENCE_TYPES),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_record_apply_submission_evidence": "{batchId:z.number().int().min(1),memberId:z.number().int().min(1),runId:z.number().int().min(1),expectedMemberVersion:z.number().int().min(1),expectedInspectionEpoch:z.number().int().min(1),leaseToken:z.string().min(1).max(1024),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/),evidenceType:z.enum(APPLY_SUBMISSION_EVIDENCE_TYPES),evidenceSource:z.enum(APPLY_SUBMISSION_EVIDENCE_SOURCES),evidenceFingerprint:z.string().regex(/^[a-f0-9]{64}$/),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_approve_apply_batch_resume": "{batchId:z.number().int().min(1),leaseToken:z.string().min(1).max(1024),membershipHash:z.string().regex(/^[a-f0-9]{64}$/),profileRevision:z.number().int().min(0),resumeId:z.number().int().min(1),resumeSha256:z.string().regex(/^[a-f0-9]{64}$/),resumeFilename:z.string().min(1).max(255),resumeSizeBytes:z.number().int().min(1),memberRuns:z.array(z.object({memberId:z.number().int().min(1),runId:z.number().int().min(1),memberVersion:z.number().int().min(1),inspectionEpoch:z.number().int().min(0)})).min(1).max(100),expiresAt:z.string().datetime(),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_certify_apply_batch_truth": "truthCertificationSchema",
+    "trackly_start_apply_run": "startApplyRunSchema",
     "trackly_get_apply_evidence": "{windowDays:z.number().int().min(1).max(365).optional(),targetReviewedRuns:z.number().int().min(1).max(1000).optional()}",
     "trackly_get_apply_protocol": "{}",
-    "trackly_report_apply_observation": "{runId:z.number().int().min(1),provider:z.string().regex(SAFE_OBSERVATION_CODE),fieldLabel:z.string().min(1).max(1000),observationType:z.string().regex(SAFE_OBSERVATION_CODE),resolutionCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),metadata:z.object({controlType:z.string().regex(SAFE_OBSERVATION_CODE).optional(),required:z.boolean().optional(),errorCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),committed:z.boolean(),scenarioCode:z.enum(APPLY_SCENARIO_CODES),browserSurface:z.enum(APPLY_BROWSER_SURFACES),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/).optional(),resumedAfterHandoff:z.boolean().optional()})}",
-    "trackly_record_application_outcome": "{runId:z.number().int().min(1),outcome:z.enum(['review_ready','submitted','failed','blocked']),confirmation:z.string().max(500).optional()}",
+    "trackly_report_apply_observation": "{runId:z.number().int().min(1),batchId:z.number().int().min(1).optional(),memberId:z.number().int().min(1).optional(),inspectionEpoch:z.number().int().min(0).optional(),leaseToken:z.string().min(1).max(1024).optional(),provider:z.string().regex(SAFE_OBSERVATION_CODE),fieldLabel:z.string().min(1).max(1000),observationType:z.string().regex(SAFE_OBSERVATION_CODE),resolutionCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),metadata:z.object({controlType:z.string().regex(SAFE_OBSERVATION_CODE).optional(),required:z.boolean().optional(),errorCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),committed:z.boolean(),scenarioCode:z.enum(APPLY_SCENARIO_CODES),browserSurface:z.enum(APPLY_BROWSER_SURFACES),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/).optional(),resumedAfterHandoff:z.boolean().optional()})}",
+    "trackly_report_apply_observations": "{observations:z.array(z.object({runId:z.number().int().min(1),batchId:z.number().int().min(1),memberId:z.number().int().min(1),inspectionEpoch:z.number().int().min(0),leaseToken:z.string().min(1).max(1024),provider:z.string().regex(SAFE_OBSERVATION_CODE),fieldLabel:z.string().min(1).max(1000),observationType:z.string().regex(SAFE_OBSERVATION_CODE),resolutionCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),metadata:z.object({controlType:z.string().regex(SAFE_OBSERVATION_CODE).optional(),required:z.boolean().optional(),errorCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),committed:z.boolean(),scenarioCode:z.enum(APPLY_SCENARIO_CODES),browserSurface:z.enum(APPLY_BROWSER_SURFACES),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/).optional(),resumedAfterHandoff:z.boolean().optional()})})).min(1).max(APPLY_BATCH_MAX_BULK_MUTATIONS)}",
+    "trackly_record_application_outcome": "{runId:z.number().int().min(1),batchId:z.number().int().min(1).optional(),memberId:z.number().int().min(1).optional(),inspectionEpoch:z.number().int().min(0).optional(),leaseToken:z.string().min(1).max(1024).optional(),outcome:z.enum(['review_ready','submitted','failed','blocked']),confirmation:z.enum(['user_confirmation','success_page']).optional()}",
+    "trackly_record_application_outcomes": "{outcomes:z.array(z.object({runId:z.number().int().min(1),batchId:z.number().int().min(1),memberId:z.number().int().min(1),inspectionEpoch:z.number().int().min(0),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)}",
     "trackly_prepare_resume": "{runId:z.number().int().min(1),browserSurface:z.enum(APPLY_BROWSER_SURFACES),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/)}",
     "trackly_verify_prepared_resume": {
-      "local": "{runId:z.number().int().min(1),confirmationId:z.string().min(1).max(200),exactLocalPath:z.string().min(1).max(4096),sha256:z.string().regex(/^[a-f0-9]{64}$/i),sizeBytes:z.number().int().min(1),expiresAt:z.string().datetime()}",
+      "local": "{runId:z.number().int().min(1),resumeId:z.number().int().min(1),confirmationId:z.string().min(1).max(200),exactLocalPath:z.string().min(1).max(4096),sha256:z.string().regex(/^[a-f0-9]{64}$/i),sizeBytes:z.number().int().min(1),expiresAt:z.string().datetime()}",
       "hosted": "{runId:z.number().int().min(1),confirmationId:z.string().min(1).max(200)}"
     }
   }

package/docs/trackly-tools.md

@@ -103,15 +103,27 @@ API-key creation attempts.
 - **trackly_get_application_profile** — Get the versioned, scoped application profile.
 - **trackly_get_profile_onboarding** — Get backend-owned questions plus only missing/unconfirmed answers.
 - **trackly_update_application_profile** — Save explicit answer states with optimistic concurrency and global/provider/company scope.
-- **trackly_start_apply_run** — Start a manual-submit browser run for a queued job.
+- **trackly_create_apply_batch** — Freeze an exact recent-first set of approved jobs with an idempotency key.
+- **trackly_get_active_apply_batch** — Recover the newest unexpired active batch before creating another after chat or browser context loss.
+- **trackly_get_apply_batch** — Page a server-owned frozen batch without reordering or replacing members.
+- **trackly_claim_apply_batch** — Acquire or renew the optimistic browser-mutation lease.
+- **trackly_checkpoint_apply_batch** — Bulk-record up to 20 value-free inspection checkpoints, typed human actions, and per-member conflicts.
+- **trackly_bind_apply_surface** — Bind an initial or recovered browser surface to the existing frozen member/run, increment its inspection epoch, and return the exact stored requisition URL.
+- **trackly_record_apply_surface_evidence** — Record current-epoch, value-free inventory, missing-tab, close-receipt, post-close absence, or close-failure evidence.
+- **trackly_record_apply_submission_evidence** — Record typed, redacted submit-request, success-page, explicit user-confirmation, or provider-receipt evidence without page text or external references.
+- **trackly_approve_apply_batch_resume** — Approve one exact default-resume identity and content hash for the complete current frozen run set.
+- **trackly_certify_apply_batch_truth** — Record an expiring late truthfulness certification over final answer and wording fingerprints after every other review-readiness gate has passed.
+- **trackly_start_apply_run** — Start or reuse a manual-submit browser run with the complete frozen batch/member/lease binding.
 - **trackly_get_apply_evidence** — Get the authenticated user's aggregate beta evidence and release gate without returning profile answers or contact values.
 - **trackly_get_apply_protocol** — Get the current ATS support, browser integrity rules, and compatible skill version.
 - **trackly_report_apply_observation** — Report redacted ATS mechanics and actual scenario coverage without answer values or page text.
+- **trackly_report_apply_observations** — Bulk-report up to 20 leased, current-epoch, batch-bound redacted observations in one request.
 - **trackly_record_application_outcome** — Record review readiness or a confirmed manual submission.
+- **trackly_record_application_outcomes** — Bulk-record up to 20 leased, batch-bound outcomes while returning per-member conflicts explicitly.
 - **trackly_prepare_resume** — Local MCP only: materialize the default resume in a private, expiring mode-0600 cache and return filename, size, SHA-256, exact local path, and visual-confirmation metadata. Hosted MCP returns a manual/local-agent requirement.
 - **trackly_verify_prepared_resume** — Local MCP only: immediately before attachment, recompute the user-confirmed resume hash and size, validate the exact path/run/expiration, and lock the file read-only. Any mismatch requires a fresh preview and confirmation.
 
-Apply contract v3 intentionally gives this verifier different local and hosted schemas: local MCP receives the full proof needed to inspect the private file, while hosted MCP accepts only run and confirmation identifiers and returns the manual/local-agent requirement. Local paths and fingerprints are never sent to the hosted verifier. Version 3.1 also records universal value-free evidence for critical-contact integrity and the manual-submit boundary. Version 3.2 authorizes the exact stored HTTPS origin for jobs Trackly ingested from employer careers sources, without granting redirect, iframe, or hostname-suffix privileges.
+Apply contract v3 intentionally gives this verifier different local and hosted schemas: local MCP receives the full proof needed to inspect the private file, while hosted MCP accepts only run and confirmation identifiers and returns the manual/local-agent requirement. Local paths are never sent remotely. Resume fingerprints are sent only to authenticated Trackly resume approval and truth-certification endpoints, never observations or employer forms. Version 3.1 also records universal value-free evidence for critical-contact integrity and the manual-submit boundary. Version 3.2 authorizes the exact stored HTTPS origin for jobs Trackly ingested from employer careers sources, without granting redirect, iframe, or hostname-suffix privileges. Version 3.3.1 adds active-batch recovery, epoch-bound observations/outcomes, and truth certification for forms with no resume control.
 
 ### Maintenance behavior
 

package/lib/agent.js

@@ -7,15 +7,17 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { apiRequest, downloadFile, getConfigPaths, hasAuth, maintenanceOutput } = require('./client');
 const { version: PACKAGE_VERSION } = require('../package.json');
-const SKILL_VERSION = '4.1.1';
+const { contractVersion: MCP_CONTRACT_VERSION } = require('../contracts/trackly-apply-tools.json');
+const SKILL_VERSION = '4.2.2';
 const CLI_USER_AGENT = `trackly-cli/${PACKAGE_VERSION}`;
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
 
 const SKILL_NAME = 'trackly-apply';
 const SKILL_MAJOR = Number(SKILL_VERSION.split('.')[0]);
-const MIN_APPLY_PROTOCOL_VERSION = '3.1.0';
+const MIN_APPLY_PROTOCOL_VERSION = '3.3.1';
 const CACHE_TTL_MS = 2 * 60 * 60 * 1000;
 const MANAGED_FILE = '.trackly-managed.json';
+const SKILL_MANIFEST_VERSION = 1;
 const RESUME_PROOF_FILE = '.trackly-resume-proof.json';
 const RESUME_PROOF_KEY_BYTES = 32;
 
@@ -52,6 +54,43 @@ function copyDirectory(source, destination) {
   }
 }
 
+function skillContentManifest(root) {
+  const files = [];
+
+  function collect(directory, relativeDirectory = '') {
+    const names = fs.readdirSync(directory).sort();
+    for (const name of names) {
+      if (!relativeDirectory && name === MANAGED_FILE) continue;
+      const absolutePath = path.join(directory, name);
+      const relativePath = relativeDirectory ? `${relativeDirectory}/${name}` : name;
+      const stat = fs.lstatSync(absolutePath);
+      if (stat.isDirectory()) {
+        collect(absolutePath, relativePath);
+        continue;
+      }
+      if (!stat.isFile()) {
+        throw new Error(`Trackly Apply skill contains an unsupported filesystem entry: ${relativePath}`);
+      }
+      const content = fs.readFileSync(absolutePath);
+      files.push({
+        path: relativePath,
+        sizeBytes: content.length,
+        sha256: crypto.createHash('sha256').update(content).digest('hex'),
+      });
+    }
+  }
+
+  collect(root);
+  const digest = crypto.createHash('sha256')
+    .update(JSON.stringify({ version: SKILL_MANIFEST_VERSION, files }))
+    .digest('hex');
+  return {
+    version: SKILL_MANIFEST_VERSION,
+    digest,
+    fileCount: files.length,
+  };
+}
+
 function managedMetadata(extra = {}) {
   return JSON.stringify({ managedBy: 'trackly-cli', skill: SKILL_NAME, skillVersion: SKILL_VERSION, ...extra }, null, 2);
 }
@@ -80,7 +119,12 @@ function installCanonicalSkill() {
   const staging = `${destination}.staging.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
   try {
     copyDirectory(source, staging);
-    fs.writeFileSync(path.join(staging, MANAGED_FILE), managedMetadata(), { mode: 0o600 });
+    const manifest = skillContentManifest(staging);
+    fs.writeFileSync(path.join(staging, MANAGED_FILE), managedMetadata({
+      skillManifestVersion: manifest.version,
+      skillContentDigest: manifest.digest,
+      skillFileCount: manifest.fileCount,
+    }), { mode: 0o600 });
   } catch (error) {
     if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
     throw error;
@@ -157,7 +201,13 @@ function linkClientSkill(client, canonical) {
     const staging = `${target}.staging.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
     try {
       copyDirectory(canonical, staging);
-      fs.writeFileSync(path.join(staging, MANAGED_FILE), managedMetadata({ copiedFrom: canonical }), { mode: 0o600 });
+      const manifest = skillContentManifest(staging);
+      fs.writeFileSync(path.join(staging, MANAGED_FILE), managedMetadata({
+        copiedFrom: canonical,
+        skillManifestVersion: manifest.version,
+        skillContentDigest: manifest.digest,
+        skillFileCount: manifest.fileCount,
+      }), { mode: 0o600 });
       fs.renameSync(staging, target);
       if (backup) fs.rmSync(backup, { recursive: true, force: true });
       return { client, target, method: 'copy', status: 'installed' };
@@ -281,10 +331,47 @@ function inspectClient(client) {
   const target = clientSkillDir(client);
   const executable = commandExists(client === 'codex' ? 'codex' : 'claude');
   const metadata = managedSkillMetadata(target);
-  const installed = fs.existsSync(path.join(target, 'SKILL.md')) && metadata?.skillVersion === SKILL_VERSION;
+  let expectedManifest = null;
+  let installedManifest = null;
+  try {
+    expectedManifest = skillContentManifest(bundledSkillDir());
+    installedManifest = skillContentManifest(target);
+  } catch (_) {}
+  const hasRecordedManifest = metadata?.skillManifestVersion === SKILL_MANIFEST_VERSION
+    && typeof metadata?.skillContentDigest === 'string'
+    && Number.isInteger(metadata?.skillFileCount);
+  const contentMatches = hasRecordedManifest
+    && expectedManifest !== null
+    && installedManifest !== null
+    && metadata.skillContentDigest === expectedManifest.digest
+    && metadata.skillContentDigest === installedManifest.digest
+    && metadata.skillFileCount === expectedManifest.fileCount
+    && metadata.skillFileCount === installedManifest.fileCount;
+  const skillIntegrity = contentMatches
+    ? 'verified'
+    : metadata && !hasRecordedManifest
+      ? 'manifest_missing'
+      : metadata
+        ? 'content_mismatch'
+        : 'not_managed';
+  const installed = fs.existsSync(path.join(target, 'SKILL.md'))
+    && metadata?.skillVersion === SKILL_VERSION
+    && skillIntegrity === 'verified';
   const mcpRegistration = mcpRegistrationState(client);
   const mcpRegistered = mcpRegistration === 'current';
-  return { client, executable, installed, installedSkillVersion: metadata?.skillVersion || null, mcpRegistered, mcpRegistration, target };
+  return {
+    client,
+    executable,
+    installed,
+    installedSkillVersion: metadata?.skillVersion || null,
+    skillIntegrity,
+    expectedSkillContentDigest: expectedManifest?.digest || null,
+    installedSkillContentDigest: installedManifest?.digest || null,
+    recordedSkillContentDigest: metadata?.skillContentDigest || null,
+    mcpRegistered,
+    mcpRegistration,
+    target,
+  };
 }
 
 function cacheDir() {
@@ -368,11 +455,21 @@ function resumeCacheName(fileName, contentType, now = Date.now(), nonce = crypto
   return path.join(`${now}-${nonce}`, safeResumeName(fileName, contentType));
 }
 
-function resumeConfirmation(fileName, sha256, sizeBytes, exactLocalPath, runId, expiresAt, confirmationId) {
+function resumeConfirmation(
+  fileName,
+  sha256,
+  sizeBytes,
+  exactLocalPath,
+  runId,
+  expiresAt,
+  confirmationId,
+  resumeId = null,
+) {
   return {
     required: true,
     source: 'trackly_default_resume',
     runId,
+    ...(resumeId == null ? {} : { resumeId }),
     confirmationId,
     fileName,
     sha256,
@@ -450,6 +547,10 @@ function verifyResumeProofSignature(manifest) {
 function materializeResume(download, options = {}) {
   const runId = Number(options.runId);
   if (!Number.isInteger(runId) || runId < 1) throw new Error('A valid Trackly Apply run ID is required before preparing a resume.');
+  const resumeId = download.resumeId == null ? null : Number(download.resumeId);
+  if (resumeId !== null && (!Number.isInteger(resumeId) || resumeId < 1)) {
+    throw new Error('Trackly returned an invalid default resume identity.');
+  }
   const now = options.now ?? Date.now();
   const nonce = options.nonce ?? crypto.randomBytes(4).toString('hex');
   const confirmationId = options.confirmationId ?? crypto.randomUUID();
@@ -471,11 +572,13 @@ function materializeResume(download, options = {}) {
     runId,
     expiresAt,
     confirmationId,
+    resumeId,
   );
   const manifestPath = path.join(path.dirname(destination), RESUME_PROOF_FILE);
   try {
     const manifest = signedResumeProof({
       runId,
+      resumeId,
       confirmationId,
       exactLocalPath: destination,
       fileName,
@@ -494,6 +597,7 @@ function materializeResume(download, options = {}) {
   }
   return {
     path: destination,
+    resumeId,
     fileName,
     contentType: validated.contentType,
     sha256: validated.digest,
@@ -542,6 +646,11 @@ function verifyPreparedResume(proof, now = Date.now()) {
   }
 
   const bindingMatches = manifest.runId === runId
+    && (
+      proof.resumeId == null
+        ? manifest.resumeId == null
+        : manifest.resumeId === Number(proof.resumeId)
+    )
     && manifest.confirmationId === proof.confirmationId
     && manifest.exactLocalPath === expectedPath
     && manifest.fileName === path.basename(expectedPath)
@@ -570,6 +679,7 @@ function verifyPreparedResume(proof, now = Date.now()) {
   return {
     verified: true,
     runId,
+    resumeId: manifest.resumeId ?? null,
     confirmationId: proof.confirmationId,
     exactLocalPath: expectedPath,
     sha256,
@@ -621,6 +731,9 @@ async function prepareResume(runId, browserSurface, browserBindingHash, userAgen
     if (Number(download.applyRunId) !== normalizedRunId) {
       throw new Error('Trackly did not confirm that the resume belongs to the active Apply run.');
     }
+    if (!Number.isInteger(Number(download.resumeId)) || Number(download.resumeId) < 1) {
+      throw new Error('Trackly did not confirm the default resume identity.');
+    }
     return materializeResume(download, { runId: normalizedRunId });
   } finally {
     download.buffer.fill(0);
@@ -631,7 +744,12 @@ function protocolAtLeast(version, minimum = MIN_APPLY_PROTOCOL_VERSION) {
   const parse = (value) => String(value || '').split('.').map((part) => Number(part));
   const actual = parse(version);
   const required = parse(minimum);
-  if (actual.length < 2 || actual.some((part) => !Number.isInteger(part) || part < 0)) return false;
+  if (
+    actual.length < 2
+    || required.length < 2
+    || actual.some((part) => !Number.isInteger(part) || part < 0)
+    || required.some((part) => !Number.isInteger(part) || part < 0)
+  ) return false;
   for (let index = 0; index < Math.max(actual.length, required.length); index++) {
     const left = actual[index] || 0;
     const right = required[index] || 0;
@@ -640,6 +758,47 @@ function protocolAtLeast(version, minimum = MIN_APPLY_PROTOCOL_VERSION) {
   return true;
 }
 
+function evaluateApplyCompatibility(protocol, clients) {
+  const compatibleSkillMajor = Number(protocol?.compatibleSkillMajor);
+  const minimumSkillVersion = typeof protocol?.compatibleSkillMinimumVersion === 'string'
+    ? protocol.compatibleSkillMinimumVersion
+    : null;
+  const minimumCliVersion = typeof protocol?.compatibleCliMinimumVersion === 'string'
+    ? protocol.compatibleCliMinimumVersion
+    : null;
+  const mcpContractCompatible = protocol?.mcpContractVersion === MCP_CONTRACT_VERSION;
+  const cliMinimumSatisfied = minimumCliVersion
+    ? protocolAtLeast(PACKAGE_VERSION, minimumCliVersion)
+    : false;
+  const protocolCompatible = compatibleSkillMajor === SKILL_MAJOR
+    && protocolAtLeast(protocol?.version, MIN_APPLY_PROTOCOL_VERSION);
+  const compatibleClientSkills = minimumSkillVersion
+    ? clients
+      .filter((client) => {
+        const installedMajor = Number(String(client.installedSkillVersion || '').split('.')[0]);
+        return client.installed === true
+          && installedMajor === compatibleSkillMajor
+          && protocolAtLeast(client.installedSkillVersion, minimumSkillVersion);
+      })
+      .map((client) => client.client)
+    : [];
+  const skillMinimumSatisfied = compatibleClientSkills.length > 0;
+  return {
+    protocolCompatible,
+    mcpContractVersion: MCP_CONTRACT_VERSION,
+    mcpContractCompatible,
+    minimumCliVersion,
+    cliMinimumSatisfied,
+    minimumSkillVersion,
+    compatibleClientSkills,
+    skillMinimumSatisfied,
+    compatible: protocolCompatible
+      && mcpContractCompatible
+      && cliMinimumSatisfied
+      && skillMinimumSatisfied,
+  };
+}
+
 function liveBrowserReady(browserControl) {
   return (browserControl?.codex === true && browserControl?.codexComputerUse === true)
     || browserControl?.claude === true;
@@ -654,13 +813,38 @@ async function doctorAgent() {
     codexComputerUse,
     claude: null,
   };
+  const tabInventory = {
+    controllerOwnedTabs: 'runtime_verification_required',
+    userOwnedTabs: 'runtime_verification_required',
+    unionReconciliation: 'runtime_verification_required',
+    detectedSurfaces: [],
+    unionInventoryDetected: false,
+    requiredForClosedClaim: true,
+    note: 'Installed plugins do not prove controller-owned and user-owned tab union inventory. The active browser client must verify both inventories before claiming a tab is closed.',
+  };
+  const clients = ['codex', 'claude'].map(inspectClient);
+  const skillIntegrityFailures = clients
+    .filter((client) => (
+      client.installedSkillVersion === SKILL_VERSION
+      && client.skillIntegrity !== 'verified'
+    ))
+    .map((client) => ({ client: client.client, integrity: client.skillIntegrity }));
   const report = {
+    cliVersion: PACKAGE_VERSION,
+    mcpContractVersion: MCP_CONTRACT_VERSION,
     skillVersion: SKILL_VERSION,
     authenticated: hasAuth(),
-    clients: ['codex', 'claude'].map(inspectClient),
+    clients,
+    skillPackIntegrity: {
+      ok: skillIntegrityFailures.length === 0,
+      expectedDigest: clients.find((client) => client.expectedSkillContentDigest)
+        ?.expectedSkillContentDigest || null,
+      failures: skillIntegrityFailures,
+    },
     browserControl: {
       ...browserControl,
       semanticReady: liveBrowserReady(browserControl),
+      tabInventory,
       note: 'A live run requires both semantic browser control and computer use. Claude capability must be verified by the active client before the run starts.',
     },
     cache,
@@ -682,8 +866,8 @@ async function doctorAgent() {
       completeness: profile.profile?.completeness,
       hasDefaultResume: Boolean(profile.profile?.defaultResume),
     };
-    report.compatible = Number(report.protocol.compatibleSkillMajor) === SKILL_MAJOR
-      && protocolAtLeast(report.protocol.version, MIN_APPLY_PROTOCOL_VERSION);
+    report.compatibility = evaluateApplyCompatibility(report.protocol, report.clients);
+    report.compatible = report.compatibility.compatible;
     if (report.profile.hasDefaultResume) {
       report.resume = {
         available: true,
@@ -697,6 +881,7 @@ async function doctorAgent() {
   report.ok = report.authenticated
     && report.compatible
     && report.browserControl.semanticReady
+    && report.skillPackIntegrity.ok
     && report.clients.some((client) => client.executable && client.installed && client.mcpRegistered)
     && Boolean(report.profile?.hasDefaultResume)
     && report.resume.available
@@ -724,6 +909,7 @@ module.exports = {
   cleanResumeCache,
   clientSkillDir,
   doctorAgent,
+  evaluateApplyCompatibility,
   inspectClient,
   liveBrowserReady,
   materializeResume,

package/lib/client.js

@@ -509,7 +509,15 @@ async function _doRefresh() {
   return null;
 }
 
-function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry = false, userAgent = null) {
+function apiRequest(
+  method,
+  endpoint,
+  data = null,
+  skipAuth = false,
+  _isRetry = false,
+  userAgent = null,
+  additionalHeaders = null
+) {
   return new Promise((resolve, reject) => {
     let url;
     try {
@@ -522,6 +530,27 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
     const isHttps = url.protocol === 'https:';
     const lib = isHttps ? https : http;
     const headers = getRequestHeaders(skipAuth, userAgent);
+    if (additionalHeaders !== null) {
+      const entries = (
+        typeof additionalHeaders === 'object'
+        && additionalHeaders !== null
+        && !Array.isArray(additionalHeaders)
+        && Object.getPrototypeOf(additionalHeaders) === Object.prototype
+      )
+        ? Object.entries(additionalHeaders)
+        : [];
+      const idempotencyEntry = entries.find(([name]) => name.toLowerCase() === 'idempotency-key');
+      if (
+        entries.length !== 1
+        || !idempotencyEntry
+        || typeof idempotencyEntry[1] !== 'string'
+        || !/^[\x20-\x7e]{16,200}$/.test(idempotencyEntry[1])
+      ) {
+        reject(new Error('Only a valid Idempotency-Key additional header is permitted.'));
+        return;
+      }
+      headers['Idempotency-Key'] = idempotencyEntry[1];
+    }
     const authMethod = getAuthMethod();
     const timeoutMs = getRequestTimeoutMs();
     const hasSensitivePayload = Boolean(data && typeof data === 'object' && 'refreshToken' in data);
@@ -604,7 +633,15 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
           }
           if (newToken) {
             try {
-              const retried = await apiRequest(method, endpoint, data, false, true, userAgent);
+              const retried = await apiRequest(
+                method,
+                endpoint,
+                data,
+                false,
+                true,
+                userAgent,
+                additionalHeaders
+              );
               return resolve(retried);
             } catch (e) { return reject(e); }
           }
@@ -730,6 +767,7 @@ function downloadFile(endpoint, userAgent = null, _isRetry = false) {
           fileName: contentDispositionFileName(disposition),
           sha256: res.headers['x-trackly-file-sha256'] || null,
           applyRunId: res.headers['x-trackly-apply-run-id'] || null,
+          resumeId: res.headers['x-trackly-resume-id'] || null,
         });
       });
     });