trackly-cli 0.13.4 → 0.14.1

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 20+](https://img.shields.io/badge/node-20+-brightgreen.svg)](https://nodejs.org/)
+[![Node 20.20+ or 22.22+](https://img.shields.io/badge/node-20.20%2B%20%7C%2022.22%2B-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 20+](https://nodejs.org/) (LTS recommended). On macOS with the official `.pkg` installer, global npm installs may require `sudo`.
+> **Prerequisites:** [Node.js 20.20+ or 22.22+](https://nodejs.org/) (LTS recommended). On macOS with the official `.pkg` installer, global npm installs may require `sudo`.
 
 ## At a Glance
 
-3,800+ companies | 170K+ jobs | 40+ ATS types | CLI + MCP | 48 local MCP tools
+3,800+ companies | 170K+ jobs | 40+ ATS types | CLI + MCP | 55 local MCP tools
 
 ## CLI Commands
 
@@ -181,6 +181,10 @@ Then use natural language in any of these clients:
 | trackly_start_apply_execution | Start a target-counted accessible Apply execution |
 | trackly_get_active_apply_execution | Recover the active execution before legacy batch recovery |
 | trackly_get_apply_execution | Read the authoritative progress funnel and immutable child waves |
+| trackly_list_recoverable_apply_executions | List bounded exact-member recovery candidates after context loss |
+| trackly_recover_exact_apply_members | Recover only one explicitly confirmed candidate set without substitutes |
+| trackly_list_apply_review_handoffs | Rediscover active, value-free review-handoff receipts for one execution |
+| trackly_claim_apply_review_handoff | Claim and classify one exact review-handoff group before reconciliation |
 | trackly_get_apply_execution_snapshot | Fetch a compact bounded projection for current execution members and required profile keys |
 | trackly_resume_parked_apply_member | Explicitly resume one parked member for a fresh non-mutating access probe |
 | trackly_approve_apply_execution_resume | Approve one exact resume identity for an unchanged execution snapshot |
@@ -204,11 +208,14 @@ Then use natural language in any of these clients:
 | trackly_report_apply_observation | Send redacted ATS mechanics feedback |
 | trackly_lint_application_text | Locally lint application writing and return only value-free violations plus a draft hash |
 | trackly_diagnose_local_path | Locally diagnose the exact implicated filesystem path without deleting files |
+| trackly_validate_apply_tab_keep_set | Locally validate an exact expected/keep tab set against complete caller-supplied inventories without controlling the browser or sending tab IDs remotely |
+| trackly_validate_apply_resume_upload | Locally validate adapter capability and ordered value-free attachment proof stages |
 | 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 |
+| get_more_tools | Report a missing capability so Trackly can improve its MCP surface |
 
 ## Authentication
 
@@ -274,7 +281,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 (48 local tools) | -- | -- |
+| MCP integration | Yes (55 local tools) | -- | -- |
 | Browser required | No | Yes | No |
 | Best for | Terminal + AI agents | Visual browsing | Custom integrations |
 
@@ -288,7 +295,18 @@ 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 48 tools for job search, company lookup, discovery preferences, application tracking, accessible execution and frozen-batch orchestration, 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 55 tools: the complete Trackly
+job-search and application set plus `get_more_tools`, which lets agents report
+a missing capability. Run `trackly mcp` or use
+`trackly agent setup --client claude`.
+
+MCP usage analytics are on by default and relay through Trackly so the free
+service can be debugged and improved. They exclude résumé text, profile answers,
+demographic or work-authorization answers, and application notes. Turn off future
+collection with **Share usage analytics** in Account Settings. Operators may also
+disable local MCP instrumentation with `TRACKLY_MCP_ANALYTICS_DISABLED=1` (or
+`TRACKLY_MCP_ANALYTICS_ENABLED=0`); the account setting remains authoritative
+for authenticated backend capture.
 
 **How do I use Claude Code for job hunting?**
 

package/bin/trackly

@@ -4,7 +4,6 @@
 const {
   DEFAULT_BASE_URL,
   apiRequest,
-  clearConfig,
   createTracklyAccessError,
   getApiKey,
   getAuthMethod,
@@ -13,6 +12,7 @@ const {
   hasAuth,
   maintenanceOutput,
   loadConfig,
+  removeCredentials,
   saveConfig,
 } = require('../lib/client');
 const { color, isJSON, outputJobs, outputCompanies, outputStats, outputContacts, outputReferralCampaign, outputNetworkBrief, outputCompanyBrief, outputCompanyWorkspace, outputError } = require('../lib/formatters');
@@ -544,7 +544,7 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
 }
 
 async function cmdLogout() {
-  clearConfig();
+  await removeCredentials({ scope: 'all' });
   console.log(color('green', 'Logged out. Credentials cleared.'));
 }
 
@@ -1055,11 +1055,12 @@ async function cmdConfig(args) {
     failNow('Cannot use --base-url and --clear-base-url together.');
   }
 
-  const config = loadConfig();
+  let config = loadConfig();
   let updated = false;
 
   if (args['clear-api-key']) {
-    delete config.apiKey;
+    await removeCredentials({ scope: 'apiKey' });
+    config = loadConfig();
     updated = true;
     console.log(color('green', 'Stored API key cleared.'));
   }
@@ -1123,8 +1124,10 @@ async function cmdVersion() {
   console.log(VERSION);
 }
 
-async function cmdMcp() {
-  await require('../mcp/server').startMcpServer();
+async function cmdMcp(options = {}) {
+  const mcpServer = options.mcpServer || require('../mcp/server');
+  const server = await mcpServer.startMcpServer(options.startOptions);
+  return mcpServer.installMcpSignalHandlers(server, options.signalOptions);
 }
 
 async function cmdAgent(args) {
@@ -1504,6 +1507,7 @@ if (require.main === module) {
 module.exports = {
   COMMAND_FLAGS,
   UNIVERSAL_FLAGS,
+  cmdMcp,
   cmdLogin,
   formatMaintenanceForHuman,
   getPublicConfig,

package/contracts/trackly-apply-contract-history.json

@@ -6,9 +6,16 @@
     "contractSha256": "8c52daa8b62095a6431d5b954505079c3f7c802e5c5ae39efa8ea7e988dfbc7a"
   },
   "3.6.2": {
-    "contractSha256": "83e107ad7ae2abdc42cdacb9848d8e3bf345951ed7b8f42d5cd9b5e203528bf2"
+    "contractSha256": "83e107ad7ae2abdc42cdacb9848d8e3bf345951ed7b8f42d5cd9b5e203528bf2",
+    "toolsSha256": "d9d24da4b79a4cc65aec589debd2b9072e41b309fd6bf6a65e95dd4b5bef3c08"
   },
   "3.6.3": {
     "contractSha256": "93a8e55196c14f04afb923711997eacdc26dbdeae50b253b906d547abd346e30"
+  },
+  "3.7.0": {
+    "toolsSha256": "8380e2a9fabef4da18ea731f55c8994aef5a4738bb6e7daef9be4ce6ebfec64f"
+  },
+  "3.7.1": {
+    "contractSha256": "0eb582fcac72804347c5da53d214a67908f657f600536db7b42167350bb3f3ab"
   }
 }

package/contracts/trackly-apply-tools.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "3.6.3",
+  "contractVersion": "3.7.1",
   "constants": {
     "applyExecutionMaxTarget": 20,
     "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"],
@@ -16,7 +16,12 @@
     "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"]
+    "applySubmissionEvidenceSources": ["submission_request", "success_page", "user_confirmation", "provider_receipt", "post_submit_receipt"],
+    "applyPositiveSubmissionStrategyCodes": ["greenhouse_confirmation_redirect", "greenhouse_semantic_success", "ashby_semantic_success_banner", "ashby_submitted_state", "lever_confirmation_redirect", "lever_semantic_confirmation"],
+    "applyExecutionRecoveryEligibilityCodes": ["recoverable", "already_applied", "inactive", "revoked", "changed_requisition", "concurrently_owned", "lineage_unavailable", "retention_expired"],
+    "applyHandoffReconciliationClassifications": ["detected", "user_confirmed", "unresolved", "contradictory"],
+    "applyUploadStages": ["semantic_control_discovered", "file_chooser_armed", "file_chooser_opened", "set_files_succeeded", "user_facing_filename_committed", "parser_fields_rechecked"],
+    "applyUploadFailureCodes": ["upload_capability_unavailable", "upload_stage_missing", "upload_stage_out_of_order", "upload_stage_duplicate", "control_ambiguous", "chooser_timeout", "chooser_open_without_commit", "file_missing", "file_expired", "set_files_failed", "filename_uncommitted", "unexpected_file_navigation", "parser_unsettled", "parser_field_regression"]
   },
   "tools": {
     "trackly_get_apply_queue": "{limit:z.number().int().min(1).max(100).optional(),cursor:z.string().min(1).max(2048).optional()}",
@@ -26,6 +31,10 @@
     "trackly_start_apply_execution": "{mode:z.literal('complete_next_n_accessible'),target:z.number().int().min(1).max(APPLY_EXECUTION_MAX_TARGET),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
     "trackly_get_active_apply_execution": "{}",
     "trackly_get_apply_execution": "{executionId:z.number().int().min(1)}",
+    "trackly_list_recoverable_apply_executions": "{}",
+    "trackly_recover_exact_apply_members": "{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)=>newSet(values).size===values.length,{message:'candidateIdsmustbeunique'}),explicitExactSetConfirmation:z.literal(true),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_list_apply_review_handoffs": "{executionId:z.number().int().min(1)}",
+    "trackly_claim_apply_review_handoff": "{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)=>newSet(values.map(({memberId})=>memberId)).size===values.length,{message:'membersmustcontainuniquememberIdvalues'}),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
     "trackly_get_apply_execution_snapshot": "{executionId:z.number().int().min(1),memberIds:z.array(z.number().int().min(1)).min(1).max(APPLY_EXECUTION_MAX_TARGET),profileKeys:z.array(z.string().min(1).max(200)).max(100).optional(),browserSurface:z.enum(APPLY_BROWSER_SURFACES)}",
     "trackly_resume_parked_apply_member": "{executionId:z.number().int().min(1),memberId:z.number().int().min(1),expectedRevision:z.number().int().min(1),browserSurface:z.enum(APPLY_BROWSER_SURFACES),explicitUserResume:z.literal(true),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
     "trackly_approve_apply_execution_resume": "{executionId:z.number().int().min(1),expectedRevision:z.number().int().min(1),originalSnapshotHash:z.string().regex(/^[a-f0-9]{64}$/),profileRevision:z.number().int().min(1),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),expiresAt:z.string().datetime(),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
@@ -48,11 +57,13 @@
     "trackly_get_apply_protocol": "{}",
     "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_record_application_outcome": "{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(),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": "{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),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).refine((values)=>newSet(values.map(({runId})=>runId)).size===values.length,{message:'outcomesmustcontainuniquerunIdvalues'})}",
     "trackly_prepare_resume": "{runId:z.number().int().min(1),browserSurface:z.enum(APPLY_BROWSER_SURFACES),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/)}",
     "trackly_lint_application_text": "{text:z.string().max(20000),emDashPolicy:z.enum(['forbid','allow_if_voice_sample','allow']).optional(),voiceSampleAllowsEmDash:z.boolean().optional(),prohibitedPhrases:z.array(z.string().min(1).max(200)).max(50).optional(),minLength:z.number().int().min(0).max(20000).optional(),maxLength:z.number().int().min(0).max(20000).optional(),claims:z.array(z.object({claimFingerprint:z.string().regex(/^[a-f0-9]{64}$/),evidenceRefs:z.array(z.string().regex(SAFE_OBSERVATION_CODE)).max(20)}).strict()).max(100),claimsComplete:z.literal(true)}",
     "trackly_diagnose_local_path": "{exactPath:z.string().min(1).max(4096),originalErrno:z.string().regex(ERRNO_PATTERN).optional()}",
+    "trackly_validate_apply_tab_keep_set": "{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()}",
+    "trackly_validate_apply_resume_upload": "{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)}",
     "trackly_verify_prepared_resume": {
       "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

@@ -72,6 +72,7 @@ API-key creation attempts.
 
 ### Available Tools
 
+- **get_more_tools** — Report what the agent wanted to do when no Trackly tool fit, so Trackly can improve its MCP surface. The tool is always available; report delivery is best-effort and occurs only when usage analytics are enabled.
 - **trackly_search_jobs** — Search/filter jobs.
   - `function` (14 values): `product`, `engineering`, `design`, `data`, `marketing`, `sales`, `partnerships`, `finance`, `strategy`, `operations`, `people`, `legal`, `support`, `other`
   - `locationFilter`: pass ONE of
@@ -106,6 +107,10 @@ API-key creation attempts.
 - **trackly_start_apply_execution** — Start a server-owned `complete_next_n_accessible` execution with a target from 1–20, then consume the returned authoritative `progress` and `nextAction` before doing browser work.
 - **trackly_get_active_apply_execution** — Recover the active execution before legacy batch recovery.
 - **trackly_get_apply_execution** — Read an execution's latest current-wave identity and authoritative aggregate progress funnel.
+- **trackly_list_recoverable_apply_executions** — List a bounded, value-free menu of exact recovery candidates after local context loss.
+- **trackly_recover_exact_apply_members** — Recover only the explicitly confirmed candidates from one retained source snapshot, with no substitutions.
+- **trackly_list_apply_review_handoffs** — Rediscover active, nonexpired review-handoff receipts for one execution without browser or profile values.
+- **trackly_claim_apply_review_handoff** — Claim one exact handoff receipt and classify every member before grouped submission reconciliation.
 - **trackly_get_apply_execution_snapshot**: Fetch a compact bounded projection of current members, requested profile keys, mutability, allowed operations, milestones, lease timing, and the authoritative funnel.
 - **trackly_resume_parked_apply_member**: Resume one parked member only after explicit user instruction; a fresh non-mutating access probe remains required before form mutation.
 - **trackly_approve_apply_execution_resume**: Approve one exact resume identity for an execution's unchanged original snapshot while preserving immediate per-run local verification before upload.
@@ -134,9 +139,16 @@ API-key creation attempts.
 - **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.
 - **trackly_lint_application_text**: Local MCP only: require an explicitly complete claim-reference packet, then return a draft hash, length, and stable value-free writing violations without sending or echoing application text to Trackly.
 - **trackly_diagnose_local_path**: Local MCP only: measure the exact implicated path's filesystem, inode, quota observability, and write-probe result without deleting user files or claiming a global disk cause.
+- **trackly_validate_apply_tab_keep_set**: Local MCP only: fail closed unless a caller-supplied nonempty expected tab set exactly matches the keep set and is covered by complete controller and user inventories. This pure helper allows unrelated tabs, performs no browser action, and never sends tab IDs to Trackly.
+- **trackly_validate_apply_resume_upload**: Local MCP only: validate the browser adapter's capabilities and ordered, value-free attachment proof stages without opening a chooser, reading a path, controlling a browser, or sending form data to Trackly.
 
 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. Version 3.4 adds server-owned accessible executions above immutable child batches, typed access dispositions, and an authoritative target-completion funnel.
 
+Version 3.7 adds public exact-member recovery and scoped review-handoff claims,
+plus local tab-finalizer and resume-upload proof validators. Recovery candidates
+are bounded and value-free. The local helpers perform no browser actions and
+send no tab IDs, filenames, paths, page text, or form values to Trackly.
+
 ### Maintenance behavior
 
 REST, refresh, download, CLI, and local/hosted MCP surfaces use canonical `code: "maintenance_mode"`; older `planned_maintenance` responses are accepted only as a compatibility alias. Structured errors retain HTTP and service status, retry time, estimated return, and request ID without clearing valid credentials. Maintenance is resumable rather than retryable: wait for the advertised window, refetch the Apply protocol and profile, then resume the existing `agent_browser` run. Never create a duplicate run or click Submit.

package/lib/agent.js

@@ -8,13 +8,13 @@ const { spawnSync } = require('node:child_process');
 const { apiRequest, downloadFile, getConfigPaths, hasAuth, maintenanceOutput } = require('./client');
 const { version: PACKAGE_VERSION } = require('../package.json');
 const { contractVersion: MCP_CONTRACT_VERSION } = require('../contracts/trackly-apply-tools.json');
-const SKILL_VERSION = '4.4.2';
+const SKILL_VERSION = '4.5.0';
 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.5.0';
+const MIN_APPLY_PROTOCOL_VERSION = '3.6.0';
 const CACHE_TTL_MS = 2 * 60 * 60 * 1000;
 const MANAGED_FILE = '.trackly-managed.json';
 const SKILL_MANIFEST_VERSION = 1;

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,
+};