trackly-cli 0.5.2 → 0.6.1

package/README.md

@@ -35,7 +35,7 @@ trackly jobs --function product
 
 ## At a Glance
 
-1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 20 local MCP tools
+1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 21 local MCP tools
 
 ## CLI Commands
 
@@ -44,6 +44,7 @@ trackly jobs                          # List jobs
 trackly jobs --remote                 # Filter remote jobs (sets usStates=REMOTE)
 trackly jobs --region us              # Filter by region (us, non_us, all, or a region tag: europe, canada, remote, ...)
 trackly jobs --job-type internship    # Filter by employment type (full_time, internship, all)
+trackly jobs --work-arrangement hybrid,remote  # Filter by work arrangement independently
 trackly jobs --function product       # Filter by function
 trackly jobs --company 243            # Filter by company ID
 trackly job 1234                      # Get job details
@@ -152,7 +153,7 @@ Then use natural language in any of these clients:
 
 | Tool | Description |
 |------|-------------|
-| trackly_search_jobs | Search and filter jobs by function, company, location, modality, status |
+| trackly_search_jobs | Search and filter jobs by function, company, region, employment type, work arrangement, and status |
 | trackly_get_job | Get full details for a specific job |
 | trackly_search_companies | Semantic company search |
 | trackly_list_companies | List all tracked companies |
@@ -172,6 +173,7 @@ Then use natural language in any of these clients:
 | trackly_report_apply_observation | Send redacted ATS mechanics feedback |
 | trackly_record_application_outcome | Record review or confirmed submission outcome |
 | trackly_prepare_resume | Prepare a private expiring resume file for upload |
+| trackly_verify_prepared_resume | Recheck the confirmed resume immediately before attachment |
 
 ## Authentication
 
@@ -245,7 +247,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 20 tools for job search, company lookup, application tracking, profile onboarding, and manual-submit form preparation. Run `trackly mcp` or use `trackly agent setup --client claude`.
+trackly-cli includes a built-in MCP server with 21 tools for job search, company lookup, application tracking, profile onboarding, 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

@@ -57,7 +57,7 @@ const COMMAND_FLAGS = {
   login: [],
   logout: [],
   whoami: [],
-  jobs: ['function', 'company', 'region', 'job-type', 'remote', 'status', 'sort', 'limit', 'offset', 'keywords', 'location', 'modality'],
+  jobs: ['function', 'company', 'region', 'job-type', 'work-arrangement', 'remote', 'status', 'sort', 'limit', 'offset', 'keywords', 'location', 'modality'],
   job: [],
   companies: ['limit', 'offset'],
   search: [],
@@ -86,6 +86,7 @@ const STATUS_LABELS = {
   saved: 'saved',
   dismissed: 'dismissed',
 };
+const WORK_ARRANGEMENT_VALUES = ['remote', 'hybrid', 'in_person', 'unspecified'];
 
 function parseArgs(args) {
   const result = { _: [], command: null };
@@ -262,7 +263,7 @@ function hasJobListFilters(args) {
   // (which then raises the migration error) instead of cmdJob(42) silently ignoring
   // the filter. See PR #13 Cursor Bugbot finding.
   const deprecated = Object.keys(DEPRECATED_JOB_FLAGS);
-  const active = ['function', 'company', 'keywords', 'limit', 'region', 'job-type', 'remote', 'offset', 'sort', 'status'];
+  const active = ['function', 'company', 'keywords', 'limit', 'region', 'job-type', 'work-arrangement', 'remote', 'offset', 'sort', 'status'];
   return [...active, ...deprecated].some((key) => args[key] !== undefined);
 }
 
@@ -506,11 +507,24 @@ async function cmdJobs(args) {
     failNow('--remote cannot be combined with --region. Use one or the other (e.g. --region remote).');
   }
 
+  let workArrangements;
+  if (args['work-arrangement'] !== undefined) {
+    if (typeof args['work-arrangement'] !== 'string' || !args['work-arrangement'].trim()) {
+      failNow('--work-arrangement requires a comma-separated value: remote, hybrid, in_person, unspecified.');
+    }
+    workArrangements = [...new Set(args['work-arrangement'].split(',').map((value) => value.trim()))];
+    const invalid = workArrangements.filter((value) => !WORK_ARRANGEMENT_VALUES.includes(value));
+    if (invalid.length > 0) {
+      failNow(`Invalid --work-arrangement value "${invalid.join(',')}". Use: ${WORK_ARRANGEMENT_VALUES.join(', ')}.`);
+    }
+  }
+
   const params = new URLSearchParams();
   if (args.function) params.set('jobFunction', args.function);
   if (args.company) params.set('companyId', args.company);
   if (args.region) params.set('locationFilter', args.region);
   if (args['job-type']) params.set('jobModality', args['job-type']);
+  if (workArrangements) params.set('workArrangements', workArrangements.join(','));
   if (args.remote) params.set('usStates', 'REMOTE');
   if (args.status) params.set('status', args.status);
   if (args.sort) params.set('sort', args.sort);
@@ -994,7 +1008,7 @@ ${color('bold', 'Commands:')}
   ${color('cyan', 'login')}                Authenticate via Google OAuth
   ${color('cyan', 'logout')}               Clear credentials
   ${color('cyan', 'whoami')}               Show current user
-  ${color('cyan', 'jobs')}                 List jobs (--function, --company <id>, --region <tag>, --job-type <type>, --remote, --status, --sort, --limit, --offset, --keywords)
+  ${color('cyan', 'jobs')}                 List jobs (--function, --company <id>, --region <tag>, --job-type <type>, --work-arrangement <values>, --remote, --status, --sort, --limit, --offset, --keywords)
   ${color('cyan', 'job <id>')}             Get full job detail
   ${color('cyan', 'jobs <id>')}            Alias for job <id>
   ${color('cyan', 'companies')}            List companies
@@ -1036,8 +1050,10 @@ ${color('bold', 'Filter values:')}
                    Use a comma-separated list of region tags for multiple regions;
                    us/non_us/all cannot be combined.
   --job-type       full_time, internship, all  (employment type, not work-location)
+  --work-arrangement
+                   remote, hybrid, in_person, unspecified (comma-separated)
   --remote         Flag (no value). Filters for remote jobs (equivalent to usStates=REMOTE).
-  --status         new, applying, applied_confirmed, check_later, not_interested, all
+  --status         new, applied_confirmed, check_later, not_interested, all
                    (filters by YOUR application pipeline state)
   --sort           newest (default), match (highest match score first, requires resume)
 

package/contracts/trackly-apply-tools.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.0.0",
+  "contractVersion": "2.0.0",
   "tools": {
     "trackly_get_apply_queue": "{limit:z.number().int().min(1).max(100).optional()}",
     "trackly_get_application_profile": "{includeSensitive:z.boolean().optional(),provider:z.string().max(100).optional(),companyId:z.string().max(100).optional()}",
@@ -9,6 +9,10 @@
     "trackly_get_apply_protocol": "{}",
     "trackly_report_apply_observation": "{runId:z.number().int().min(1).optional(),provider:z.string().min(1).max(100),fieldLabel:z.string().min(1).max(1000),observationType:z.string().min(1).max(100),resolutionCode:z.string().max(100).optional(),metadata:z.object({controlType:z.string().max(100).optional(),required:z.boolean().optional(),errorCode:z.string().max(100).optional(),committed:z.boolean().optional()}).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_prepare_resume": "{}"
+    "trackly_prepare_resume": "{runId:z.number().int().min(1)}",
+    "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()}",
+      "hosted": "{runId:z.number().int().min(1),confirmationId:z.string().min(1).max(200)}"
+    }
   }
 }

package/docs/trackly-tools.md

@@ -72,9 +72,10 @@ You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
   - `locationFilter`: pass ONE of
     - a single scalar: `us`, `non_us`, `all`, or a region tag (`europe`, `latam`, `middle_east`, `asia`, `africa`, `canada`, `oceania`, `remote`, `unknown`), OR
     - an array of region tags for multi-region (e.g. `["europe", "canada"]`). The array form excludes `us` — combining `us` with other tags in an array causes the backend to silently drop the others. To get "not US" use the scalar `non_us` alone.
-  - `jobModality`: `full_time`, `internship`, `all` — employment type, NOT work-location style. For remote filtering, use the `remote` boolean or `locationFilter: "remote"`. Hybrid and onsite are not exposed as filters.
+  - `jobModality`: `full_time`, `internship`, `all` — employment type, NOT work arrangement.
+  - `workArrangements`: one or more of `remote`, `hybrid`, `in_person`, `unspecified`. This is an independent axis and combines with region, employment type, and function filters.
   - `remote` (boolean): filter to remote jobs only. Maps to `usStates=REMOTE`.
-  - `status`: your application pipeline state. Values: `new`, `applied_confirmed`, `check_later`, `not_interested`, `all`. Older `applying` requests are accepted by the backend as a private compatibility alias for `check_later`, but new clients must not emit it.
+  - `status`: your application pipeline state. Values: `new`, `applied_confirmed`, `check_later`, `not_interested`, `all`.
   - `sort`: `newest` (default) or `match` (highest match score first; requires a resume on file). Backend rejects the deprecated values `oldest` and `company` with HTTP 400.
   - `keywords`, `companyId`, `limit`, `offset`.
 - **trackly_get_job** — Get full job details by ID
@@ -95,7 +96,10 @@ You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
 - **trackly_get_apply_protocol** — Get the current ATS support, browser integrity rules, and compatible skill version.
 - **trackly_report_apply_observation** — Report redacted ATS mechanics without answer values.
 - **trackly_record_application_outcome** — Record review readiness or a confirmed manual submission.
-- **trackly_prepare_resume** — Local MCP only: materialize the default resume in a private, expiring mode-0600 cache. Hosted MCP returns a manual/local-agent requirement.
+- **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 v2 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.
 
 ### Maintenance behavior
 

package/lib/agent.js

@@ -7,7 +7,7 @@ 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 = '1.0.1';
+const SKILL_VERSION = '2.0.0';
 const CLI_USER_AGENT = `trackly-cli/${PACKAGE_VERSION}`;
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
 
@@ -15,6 +15,8 @@ const SKILL_NAME = 'trackly-apply';
 const SKILL_MAJOR = Number(SKILL_VERSION.split('.')[0]);
 const CACHE_TTL_MS = 2 * 60 * 60 * 1000;
 const MANAGED_FILE = '.trackly-managed.json';
+const RESUME_PROOF_FILE = '.trackly-resume-proof.json';
+const RESUME_PROOF_KEY_BYTES = 32;
 
 function bundledSkillDir() {
   return path.join(__dirname, '..', 'skills', SKILL_NAME);
@@ -292,26 +294,288 @@ function cleanResumeCache(now = Date.now()) {
   const dir = cacheDir();
   if (!fs.existsSync(dir)) return { removed: 0, directory: dir };
   let removed = 0;
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isFile()) continue;
-    const file = path.join(dir, entry.name);
-    const stat = fs.statSync(file);
-    if (now - stat.mtimeMs > CACHE_TTL_MS) {
-      fs.rmSync(file, { force: true });
-      removed++;
+
+  function ignoreConcurrentRemoval(error, codes = ['ENOENT']) {
+    if (codes.includes(error?.code)) return true;
+    throw error;
+  }
+
+  function cleanDirectory(current, removeWhenExpired = false) {
+    let directoryStat;
+    try {
+      directoryStat = fs.lstatSync(current);
+    } catch (error) {
+      if (ignoreConcurrentRemoval(error)) return;
+    }
+    if (!directoryStat.isDirectory()) return;
+    const directoryExpired = removeWhenExpired && now - directoryStat.mtimeMs > CACHE_TTL_MS;
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch (error) {
+      if (ignoreConcurrentRemoval(error)) return;
+    }
+    for (const entry of entries) {
+      const item = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        cleanDirectory(item, true);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      let stat;
+      try {
+        stat = fs.lstatSync(item);
+      } catch (error) {
+        if (ignoreConcurrentRemoval(error)) continue;
+      }
+      if (!stat.isFile()) continue;
+      if (now - stat.mtimeMs > CACHE_TTL_MS) {
+        try {
+          fs.rmSync(item, { force: true });
+          removed++;
+        } catch (error) {
+          if (!ignoreConcurrentRemoval(error)) throw error;
+        }
+      }
+    }
+    if (!directoryExpired) return;
+    try {
+      if (fs.readdirSync(current).length === 0) fs.rmdirSync(current);
+    } catch (error) {
+      ignoreConcurrentRemoval(error, ['ENOENT', 'ENOTEMPTY']);
     }
   }
+
+  cleanDirectory(dir);
   return { removed, directory: dir };
 }
 
 function safeResumeName(fileName, contentType) {
   const extension = contentType === 'application/pdf' ? '.pdf' : '.docx';
-  const base = path.basename(fileName || `resume${extension}`).replace(/[^A-Za-z0-9._ -]/g, '_').slice(0, 120);
-  return base.toLowerCase().endsWith(extension) ? base : `${base}${extension}`;
+  const value = fileName == null || fileName === '' ? `resume${extension}` : String(fileName);
+  const invalid = value === '.'
+    || value === '..'
+    || value !== value.trim()
+    || /[\\/\0-\x1f\x7f]/.test(value)
+    || Buffer.byteLength(value, 'utf8') > 240
+    || !value.toLowerCase().endsWith(extension);
+  if (invalid) throw new Error('Trackly returned an unsafe or incompatible resume filename. Update the default resume and try again.');
+  return value;
 }
 
 function resumeCacheName(fileName, contentType, now = Date.now(), nonce = crypto.randomBytes(4).toString('hex')) {
-  return `${now}-${nonce}-${safeResumeName(fileName, contentType)}`;
+  return path.join(`${now}-${nonce}`, safeResumeName(fileName, contentType));
+}
+
+function resumeConfirmation(fileName, sha256, sizeBytes, exactLocalPath, runId, expiresAt, confirmationId) {
+  return {
+    required: true,
+    source: 'trackly_default_resume',
+    runId,
+    confirmationId,
+    fileName,
+    sha256,
+    sizeBytes,
+    expiresAt,
+    verification: {
+      preferred: 'local_preview',
+      exactLocalPath,
+      displayExactPathRequired: true,
+    },
+  };
+}
+
+function resumeProofKey() {
+  const configDir = path.resolve(getConfigPaths().dir);
+  ensureDir(configDir, 0o700);
+  const keyPath = path.join(configDir, 'resume-proof.key');
+
+  function readExistingKey() {
+    const stat = fs.lstatSync(keyPath);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) {
+      throw new Error('The Trackly resume-proof key is not a private regular file.');
+    }
+    const key = fs.readFileSync(keyPath);
+    if (key.length !== RESUME_PROOF_KEY_BYTES) throw new Error('The Trackly resume-proof key is invalid.');
+    return key;
+  }
+
+  try {
+    return readExistingKey();
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+
+  const candidate = crypto.randomBytes(RESUME_PROOF_KEY_BYTES);
+  try {
+    fs.writeFileSync(keyPath, candidate, { mode: 0o600, flag: 'wx' });
+    fs.chmodSync(keyPath, 0o600);
+    return candidate;
+  } catch (error) {
+    candidate.fill(0);
+    if (error?.code !== 'EEXIST') throw error;
+    return readExistingKey();
+  }
+}
+
+function signedResumeProof(record) {
+  const payload = JSON.stringify(record);
+  const key = resumeProofKey();
+  try {
+    return {
+      ...record,
+      signature: crypto.createHmac('sha256', key).update(payload).digest('hex'),
+    };
+  } finally {
+    key.fill(0);
+  }
+}
+
+function verifyResumeProofSignature(manifest) {
+  const { signature, ...record } = manifest || {};
+  if (!/^[a-f0-9]{64}$/i.test(signature || '')) throw new Error('The prepared resume proof is invalid. Prepare and confirm it again.');
+  const key = resumeProofKey();
+  try {
+    const expected = crypto.createHmac('sha256', key).update(JSON.stringify(record)).digest();
+    if (!crypto.timingSafeEqual(expected, Buffer.from(signature, 'hex'))) {
+      throw new Error('The prepared resume proof is invalid. Prepare and confirm it again.');
+    }
+  } finally {
+    key.fill(0);
+  }
+  return record;
+}
+
+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 now = options.now ?? Date.now();
+  const nonce = options.nonce ?? crypto.randomBytes(4).toString('hex');
+  const confirmationId = options.confirmationId ?? crypto.randomUUID();
+  const validated = validateResumeFile(download);
+  const dir = cacheDir();
+  ensureDir(dir, 0o700);
+  const name = resumeCacheName(download.fileName, validated.contentType, now, nonce);
+  const destination = path.join(dir, name);
+  ensureDir(path.dirname(destination), 0o700);
+  fs.writeFileSync(destination, download.buffer, { mode: 0o600, flag: 'wx' });
+  try { fs.chmodSync(destination, 0o600); } catch (_) {}
+  const fileName = path.basename(destination);
+  const expiresAt = new Date(now + CACHE_TTL_MS).toISOString();
+  const confirmation = resumeConfirmation(
+    fileName,
+    validated.digest,
+    download.buffer.length,
+    destination,
+    runId,
+    expiresAt,
+    confirmationId,
+  );
+  const manifestPath = path.join(path.dirname(destination), RESUME_PROOF_FILE);
+  try {
+    const manifest = signedResumeProof({
+      runId,
+      confirmationId,
+      exactLocalPath: destination,
+      fileName,
+      sha256: validated.digest,
+      sizeBytes: download.buffer.length,
+      expiresAt,
+    });
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest), { mode: 0o400, flag: 'wx' });
+    fs.chmodSync(manifestPath, 0o400);
+  } catch (error) {
+    fs.rmSync(destination, { force: true });
+    try { fs.rmdirSync(path.dirname(destination)); } catch (cleanupError) {
+      if (!['ENOENT', 'ENOTEMPTY'].includes(cleanupError?.code)) throw cleanupError;
+    }
+    throw error;
+  }
+  return {
+    path: destination,
+    fileName,
+    contentType: validated.contentType,
+    sha256: validated.digest,
+    sizeBytes: download.buffer.length,
+    expiresAt,
+    confirmation,
+  };
+}
+
+function verifyPreparedResume(proof, now = Date.now()) {
+  const runId = Number(proof?.runId);
+  if (!Number.isInteger(runId) || runId < 1) throw new Error('A valid Trackly Apply run ID is required to verify a prepared resume.');
+  if (!proof?.confirmationId || typeof proof.confirmationId !== 'string') throw new Error('The prepared resume confirmation ID is required.');
+  if (!/^[a-f0-9]{64}$/i.test(proof?.sha256 || '')) throw new Error('The prepared resume SHA-256 is invalid.');
+  if (!Number.isInteger(proof?.sizeBytes) || proof.sizeBytes < 1) throw new Error('The prepared resume size is invalid.');
+  const expiresAtMs = Date.parse(proof?.expiresAt || '');
+  if (!Number.isFinite(expiresAtMs) || expiresAtMs <= now) throw new Error('The prepared resume confirmation expired. Prepare and confirm the resume again.');
+
+  const expectedPath = path.resolve(String(proof?.exactLocalPath || ''));
+  const cacheRoot = path.resolve(cacheDir());
+  if (!expectedPath.startsWith(`${cacheRoot}${path.sep}`)) throw new Error('The prepared resume path is outside the private Trackly cache.');
+
+  let realPath;
+  try {
+    realPath = fs.realpathSync(expectedPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new Error('The prepared resume no longer exists. Prepare and confirm the resume again.');
+    throw error;
+  }
+  const realCacheRoot = fs.realpathSync(cacheRoot);
+  if (!realPath.startsWith(`${realCacheRoot}${path.sep}`)) throw new Error('The prepared resume resolves outside the private Trackly cache.');
+
+  let manifest;
+  try {
+    const manifestPath = path.join(path.dirname(expectedPath), RESUME_PROOF_FILE);
+    const manifestStat = fs.lstatSync(manifestPath);
+    if (!manifestStat.isFile() || manifestStat.isSymbolicLink() || (manifestStat.mode & 0o077) !== 0) {
+      throw new Error('The prepared resume proof is not private. Prepare and confirm it again.');
+    }
+    manifest = verifyResumeProofSignature(JSON.parse(fs.readFileSync(manifestPath, 'utf8')));
+  } catch (error) {
+    if (error instanceof SyntaxError || error?.code === 'ENOENT') {
+      throw new Error('The prepared resume proof is missing or invalid. Prepare and confirm it again.');
+    }
+    throw error;
+  }
+
+  const bindingMatches = manifest.runId === runId
+    && manifest.confirmationId === proof.confirmationId
+    && manifest.exactLocalPath === expectedPath
+    && manifest.fileName === path.basename(expectedPath)
+    && manifest.sha256 === proof.sha256
+    && manifest.sizeBytes === proof.sizeBytes
+    && manifest.expiresAt === proof.expiresAt;
+  if (!bindingMatches) throw new Error('The prepared resume proof does not match the confirmed run and file. Prepare and confirm it again.');
+
+  let stat;
+  try {
+    stat = fs.lstatSync(expectedPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new Error('The prepared resume no longer exists. Prepare and confirm the resume again.');
+    throw error;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('The prepared resume is not a regular private cache file.');
+  if ((stat.mode & 0o077) !== 0) throw new Error('The prepared resume permissions are not private.');
+  if (stat.size !== proof.sizeBytes) throw new Error('The prepared resume size changed after confirmation. Prepare and confirm it again.');
+
+  const sha256 = crypto.createHash('sha256').update(fs.readFileSync(expectedPath)).digest('hex');
+  if (!crypto.timingSafeEqual(Buffer.from(sha256, 'hex'), Buffer.from(proof.sha256, 'hex'))) {
+    throw new Error('The prepared resume contents changed after confirmation. Prepare and confirm it again.');
+  }
+
+  fs.chmodSync(expectedPath, 0o400);
+  return {
+    verified: true,
+    runId,
+    confirmationId: proof.confirmationId,
+    exactLocalPath: expectedPath,
+    sha256,
+    sizeBytes: stat.size,
+    expiresAt: new Date(expiresAtMs).toISOString(),
+    permissions: '400',
+  };
 }
 
 function validateResumeFile(download) {
@@ -333,25 +597,22 @@ function validateResumeFile(download) {
   };
 }
 
-async function prepareResume(userAgent = MCP_USER_AGENT) {
+async function prepareResume(runId, userAgent = MCP_USER_AGENT) {
   if (!hasAuth()) throw new Error('Authenticate first with `trackly login` or `trackly config --api-key ...`.');
+  const normalizedRunId = Number(runId);
+  if (!Number.isInteger(normalizedRunId) || normalizedRunId < 1) {
+    throw new Error('A valid Trackly Apply run ID is required before preparing a resume.');
+  }
   cleanResumeCache();
-  const download = await downloadFile('/api/jobscout/application-profile/default-resume', userAgent);
+  const download = await downloadFile(
+    `/api/jobscout/application-profile/default-resume?runId=${normalizedRunId}`,
+    userAgent,
+  );
   try {
-    const validated = validateResumeFile(download);
-    const dir = cacheDir();
-    ensureDir(dir, 0o700);
-    const name = resumeCacheName(download.fileName, validated.contentType);
-    const destination = path.join(dir, name);
-    fs.writeFileSync(destination, download.buffer, { mode: 0o600, flag: 'wx' });
-    try { fs.chmodSync(destination, 0o600); } catch (_) {}
-    return {
-      path: destination,
-      fileName: path.basename(destination),
-      contentType: validated.contentType,
-      sha256: validated.digest,
-      expiresAt: new Date(Date.now() + CACHE_TTL_MS).toISOString(),
-    };
+    if (Number(download.applyRunId) !== normalizedRunId) {
+      throw new Error('Trackly did not confirm that the resume belongs to the active Apply run.');
+    }
+    return materializeResume(download, { runId: normalizedRunId });
   } finally {
     download.buffer.fill(0);
   }
@@ -372,7 +633,7 @@ async function doctorAgent() {
     cache,
     protocol: null,
     profile: null,
-    resume: { verified: false },
+    resume: { available: false },
     compatible: false,
     ok: false,
   };
@@ -390,24 +651,11 @@ async function doctorAgent() {
     };
     report.compatible = Number(report.protocol.compatibleSkillMajor) === SKILL_MAJOR;
     if (report.profile.hasDefaultResume) {
-      try {
-        const prepared = await prepareResume(CLI_USER_AGENT);
-        const mode = fs.statSync(prepared.path).mode & 0o777;
-        report.resume = {
-          verified: mode === 0o600,
-          contentType: prepared.contentType,
-          permissions: mode.toString(8).padStart(3, '0'),
-          expiresAt: prepared.expiresAt,
-        };
-        if (!report.resume.verified) report.resume.error = 'Prepared resume cache file is not mode 0600.';
-      } catch (error) {
-        const maintenance = maintenanceOutput(error);
-        report.resume = {
-          verified: false,
-          error: error.error || error.message || String(error),
-          ...(maintenance ? { maintenance } : {}),
-        };
-      }
+      report.resume = {
+        available: true,
+        fileName: profile.profile.defaultResume.fileName || null,
+        validation: 'Exact bytes are prepared and verified only after a real Apply run starts.',
+      };
     }
   } catch (error) {
     report.apiError = maintenanceOutput(error) || error.error || error.message || String(error);
@@ -416,14 +664,16 @@ async function doctorAgent() {
     && report.compatible
     && report.clients.some((client) => client.executable && client.installed && client.mcpRegistered)
     && Boolean(report.profile?.hasDefaultResume)
-    && report.resume.verified
+    && report.resume.available
     && report.profile?.completeness?.missingKeys?.length === 0;
   return report;
 }
 
 function resumeValidationStatus(report) {
   if (!report?.profile?.hasDefaultResume) return 'not applicable (no default resume set)';
-  return report.resume?.verified ? 'passed' : 'failed';
+  return report.resume?.available
+    ? 'available (exact bytes are verified during an active Apply run)'
+    : 'failed';
 }
 
 module.exports = {
@@ -439,9 +689,12 @@ module.exports = {
   clientSkillDir,
   doctorAgent,
   inspectClient,
+  materializeResume,
   prepareResume,
+  resumeConfirmation,
   resumeCacheName,
   resumeValidationStatus,
   setupAgent,
   validateResumeFile,
+  verifyPreparedResume,
 };

package/lib/client.js

@@ -680,12 +680,12 @@ function downloadFile(endpoint, userAgent = null, _isRetry = false) {
           return;
         }
         const disposition = String(res.headers['content-disposition'] || '');
-        const match = disposition.match(/filename="?([^";]+)"?/i);
         resolve({
           buffer,
           contentType: String(res.headers['content-type'] || 'application/octet-stream').split(';')[0],
-          fileName: match ? match[1] : null,
+          fileName: contentDispositionFileName(disposition),
           sha256: res.headers['x-trackly-file-sha256'] || null,
+          applyRunId: res.headers['x-trackly-apply-run-id'] || null,
         });
       });
     });
@@ -695,6 +695,24 @@ function downloadFile(endpoint, userAgent = null, _isRetry = false) {
   });
 }
 
+function contentDispositionFileName(disposition) {
+  const value = String(disposition || '');
+  const extended = value.match(/(?:^|;)\s*filename\*\s*=\s*(?:"([^"]*)"|([^;]*))/i);
+  if (extended) {
+    const encoded = extended[1] != null ? extended[1] : String(extended[2] ?? '').trim();
+    const match = encoded.match(/^([^']*)'[^']*'(.*)$/s);
+    const charset = match ? match[1].toLowerCase() : 'utf-8';
+    const payload = match ? match[2] : encoded;
+    if (charset === 'utf-8' || charset === 'utf8') {
+      try { return decodeURIComponent(payload); } catch (_) {}
+    }
+  }
+  const basic = value.match(/(?:^|;)\s*filename\s*=\s*(?:"([^"]*)"|([^;]*))/i);
+  if (!basic) return null;
+  const fileName = basic[1] != null ? basic[1] : String(basic[2] ?? '').trim();
+  return fileName || null;
+}
+
 module.exports = {
   DEFAULT_BASE_URL,
   DEFAULT_CONFIG_DIR,
@@ -706,6 +724,7 @@ module.exports = {
   downloadFile,
   clearConfig,
   clearOAuthTokens,
+  contentDispositionFileName,
   ensureSecureUrl,
   getApiKey,
   getAuthHeader,

package/mcp/server.js

@@ -5,7 +5,7 @@ const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio
 const { McpError } = require('@modelcontextprotocol/sdk/types.js');
 const { z } = require('zod');
 const { apiRequest, hasAuth, maintenanceOutput } = require('../lib/client');
-const { prepareResume } = require('../lib/agent');
+const { prepareResume, verifyPreparedResume } = require('../lib/agent');
 const { version: PACKAGE_VERSION } = require('../package.json');
 
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
@@ -40,6 +40,10 @@ const STATUS_VALUES = ['new', 'applied_confirmed', 'check_later', 'not_intereste
 // `jobModality` enum matches `jobscout.ts:2870-2875`. Employment type, NOT work-location.
 const JOB_MODALITIES = ['full_time', 'internship', 'all'];
 
+// Independent from geography and employment type. Matches the backend's
+// workArrangements query contract and job_postings constraint.
+const WORK_ARRANGEMENTS = ['remote', 'hybrid', 'in_person', 'unspecified'];
+
 // `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'];
@@ -126,7 +130,7 @@ function createServer() {
 
   server.tool(
     'trackly_search_jobs',
-    'Search and filter job postings. Returns matching jobs with title, company, location, and structured fields. Use companyId to filter jobs at a specific company (get companyId from trackly_search_companies first). Pass `remote: true` for remote-only jobs.',
+    'Search and filter job postings. Returns matching jobs with title, company, location, and structured fields. Use companyId to filter jobs at a specific company (get companyId from trackly_search_companies first). Work arrangement is independent from region and employment type: use workArrangements for remote, hybrid, in-person, or unspecified classifications.',
     {
       function: z.enum(JOB_FUNCTIONS).optional().describe('Job function filter. One of: ' + JOB_FUNCTIONS.join(', ')),
       companyId: z.number().optional().describe('Filter jobs by company ID (get from trackly_search_companies)'),
@@ -138,7 +142,10 @@ function createServer() {
         "Region tag filter. Pass ONE of: (a) a single scalar from 'us', 'non_us', 'all', or a REGION_TAGS value ('europe', 'latam', 'middle_east', 'asia', 'africa', 'canada', 'oceania', 'remote', 'unknown'); or (b) an array of region tags for multi-region (e.g. ['europe', 'canada']). The array form excludes 'us' — combining 'us' with other tags causes the backend to silently drop the others. For 'not US' use the scalar 'non_us' alone."
       ),
       jobModality: z.enum(JOB_MODALITIES).optional().describe(
-        "Employment type (NOT work-location style). full_time = full-time roles, internship = internships, all = both. For remote filtering, use the `remote` boolean or locationFilter='remote'. Hybrid and onsite are not exposed as filters."
+        'Employment type (NOT work arrangement). full_time = full-time roles, internship = internships, all = both. Use workArrangements for remote, hybrid, or in-person classification.'
+      ),
+      workArrangements: z.array(z.enum(WORK_ARRANGEMENTS)).min(1).max(4).optional().describe(
+        'Work arrangement filter, independent from geography and employment type. Values: remote, hybrid, in_person, unspecified. Multiple values use OR semantics.'
       ),
       remote: z.boolean().optional().describe('Filter to remote jobs only (maps to usStates=REMOTE).'),
       status: z.enum(STATUS_VALUES).optional().describe(
@@ -168,6 +175,7 @@ function createServer() {
         qs.set('locationFilter', value);
       }
       if (params.jobModality !== undefined) qs.set('jobModality', params.jobModality);
+      if (params.workArrangements !== undefined) qs.set('workArrangements', params.workArrangements.join(','));
       if (params.remote === true) qs.set('usStates', 'REMOTE');
       if (params.status !== undefined) qs.set('status', params.status);
       if (params.sort !== undefined) qs.set('sort', params.sort);
@@ -461,9 +469,23 @@ function createServer() {
 
   server.tool(
     'trackly_prepare_resume',
-    'Download the authenticated default resume into a mode-0600 temporary Trackly cache for browser upload.',
-    {},
-    wrapTool(async () => prepareResume(), 'Failed to prepare default resume')
+    'Download the authenticated default resume into a mode-0600 temporary Trackly cache and return exact-file proof for user confirmation before browser upload.',
+    { runId: z.number().int().min(1) },
+    wrapTool(async ({ runId }) => prepareResume(runId), 'Failed to prepare default resume')
+  );
+
+  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.',
+    {
+      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(),
+    },
+    wrapTool(async (proof) => verifyPreparedResume(proof), 'Prepared resume integrity verification failed')
   );
 
   server.registerPrompt('trackly-apply', {
@@ -474,7 +496,7 @@ function createServer() {
       role: 'user',
       content: {
         type: 'text',
-        text: 'Fetch the Trackly Apply protocol and profile onboarding, resolve missing answers with me, start the next approved queue run, fill the form, verify every required field, and stop before Submit. If maintenance interrupts the run, retain the run and browser context, wait for the advertised window, refetch protocol and profile state, and resume the existing agent_browser run. Never start a duplicate run, blindly retry a mutation, or click Submit.',
+        text: 'Fetch the Trackly Apply protocol and profile onboarding, resolve missing answers with me, and start the next approved queue run. Prepare the run-bound resume locally, show me its exact path, filename, size, SHA-256, run, and expiration, and obtain my explicit confirmation. Immediately before attachment, use the local verifier to validate the signed proof, recompute hash and size, check expiration, and lock the file read-only. Then fill the form, verify every required field, and stop before Submit. If maintenance interrupts the run, retain the run and browser context, wait for the advertised window, refetch protocol and profile state, and resume the existing agent_browser run. Never start a duplicate run, blindly retry a mutation, or click Submit.',
       },
     }],
   }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "mcpName": "io.github.trackly-app/trackly",
   "description": "AI job search CLI + hosted MCP server with OAuth. 128K+ jobs, 1,900+ companies, 40+ ATS. Works with Claude, ChatGPT, Cursor, Windsurf, Codex via hosted streamable-http or local stdio.",
   "bin": {

package/server.json

@@ -17,12 +17,12 @@
       ]
     }
   ],
-  "version": "0.5.2",
+  "version": "0.6.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.5.2",
+      "version": "0.6.1",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {

package/skills/trackly-apply/SKILL.md

@@ -30,7 +30,17 @@ Use Trackly as the source of truth for profile answers, documents, queue decisio
 4. Require the one-time profile confirmation, complete education entries, and a default resume before browser work.
 5. Call `trackly_get_apply_queue`. Select deterministically unless the user names a job. Do not replace the queue call with a fresh job search.
 6. Call `trackly_start_apply_run` for the selected job.
-7. Call `trackly_prepare_resume`. If hosted MCP reports it unavailable, tell the user that local Trackly MCP or manual upload is required.
+7. Call `trackly_prepare_resume` with the active application run ID. If hosted MCP reports it unavailable, tell the user that local Trackly MCP or manual upload is required.
+8. Preserve the user’s filename returned by `trackly_prepare_resume`. Internal cache identifiers belong only in private parent directories and must never appear in the employer-facing upload filename.
+9. Before any upload, let the user inspect the exact prepared file returned by `trackly_prepare_resume`:
+   - Prefer an inline visual preview. Otherwise open the exact local file in Quick Look or Preview.app.
+   - Show a compact proof block with source (`Trackly default resume`), exact local path, user-facing filename, file size, SHA-256 fingerprint, application run, and expiration.
+   - Ask for explicit confirmation to use that resume. Bind confirmation to the exact SHA-256 and current application run; a different hash or run requires new confirmation.
+   - Always provide `confirmation.verification.exactLocalPath` so the user can independently verify the file. Never describe the prepared cache path as the original upload source.
+   - If an original local source path is known from the current session, identify it separately. Do not store original device paths in Trackly.
+   - A generic profile page is not proof of the prepared file. Use an app or web deep link only when the current protocol supplies an authenticated exact-resume viewer tied to the same SHA-256.
+   - If no exact preview method works, stop and ask the user to inspect the file manually.
+10. After the user confirms and immediately before attachment, call local `trackly_verify_prepared_resume` with the confirmed run ID, confirmation ID, exact path, SHA-256, size, and expiration. Continue only when it returns `verified: true` for exactly those values. The verifier validates the signed prepare-issued proof, recomputes the file hash, and locks it read-only. If it is unavailable, expired, missing, or mismatched, stop; prepare and visually confirm a fresh copy or require manual upload. Never send a local path or fingerprint to the hosted verifier.
 
 ## Resume after maintenance
 
@@ -50,7 +60,7 @@ Follow this order:
 
 1. Open the application in the controlled browser context and confirm the employer, role, ATS host, and HTTPS URL.
 2. Inspect the whole form and identify required fields, semantic controls, consent controls, document inputs, and multi-step sections.
-3. Upload the prepared resume before autofill when parsing may overwrite contact fields. Verify the filename chip.
+3. Only after the exact-hash visual confirmation and a successful immediate pre-attach `trackly_verify_prepared_resume` check, upload the prepared resume before autofill when parsing may overwrite contact fields. Do not change the file between verification and attachment. Verify that the filename chip exactly matches the prepared resume’s user-facing filename and contains no internal cache identifier. Stop and replace the attachment if it does not.
 4. Fill typed fields from the resolved Trackly profile. Clear parser-filled data when the canonical state is intentionally blank.
 5. Use real UI clicks for React/native selects, radios, and checkboxes. After every selection, verify the committed value and disappearance of the required-field error.
 6. Recheck email and phone through both browser DOM state and macOS accessibility state. Require exact values and reject duplicate/concatenated values.

package/skills/trackly-apply/references/review-handoff.md

@@ -8,6 +8,10 @@ Ready for your review — not submitted
 Company / role:
 ATS / URL:
 Resume:
+Resume visual confirmation: yes/no
+Resume exact local path:
+Resume fingerprint / size:
+Resume confirmation run / expiration:
 Critical contact values verified: yes/no
 Authorization / sponsorship:
 Compensation answer: