trackly-cli 0.7.3 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "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": {
@@ -8,7 +8,9 @@
   },
   "scripts": {
     "test": "node --test",
-    "test:hosted-contract": "node scripts/verify-hosted-contract.js"
+    "test:contract-fixture": "node --test test/apply-contract.test.js",
+    "test:hosted-contract": "node scripts/verify-hosted-contract.js",
+    "security:audit": "node scripts/verify-audit-exceptions.js"
   },
   "files": [
     "bin/",
@@ -17,6 +19,9 @@
     "skills/",
     "contracts/",
     "docs/",
+    "scripts/verify-audit-exceptions.js",
+    "security/audit-exceptions.json",
+    "npm-shrinkwrap.json",
     "server.json",
     "README.md",
     "LICENSE"
@@ -57,11 +62,14 @@
     "url": "https://github.com/trackly-app/trackly-cli/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "hono": "^4.12.30",
     "zod": "^3.23.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
+  },
+  "overrides": {
+    "@hono/node-server": "2.0.12"
   }
 }

package/scripts/verify-audit-exceptions.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const DEFAULT_POLICY_PATH = path.join(
+  __dirname,
+  '..',
+  'security',
+  'audit-exceptions.json',
+);
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+function selectAdvisoryFields(advisory) {
+  return {
+    source: advisory.source,
+    name: advisory.name,
+    dependency: advisory.dependency,
+    title: advisory.title,
+    url: advisory.url,
+    severity: advisory.severity,
+    cwe: advisory.cwe,
+    cvss: advisory.cvss,
+    range: advisory.range,
+  };
+}
+
+function selectVulnerabilityFields(vulnerability) {
+  return {
+    name: vulnerability.name,
+    severity: vulnerability.severity,
+    isDirect: vulnerability.isDirect,
+    via: vulnerability.via.map((entry) => (
+      typeof entry === 'string' ? entry : selectAdvisoryFields(entry)
+    )),
+    effects: vulnerability.effects,
+    range: vulnerability.range,
+    nodes: vulnerability.nodes,
+  };
+}
+
+function normalizedAuditShape(report) {
+  const vulnerabilities = {};
+  for (const packageName of Object.keys(report.vulnerabilities || {}).sort()) {
+    vulnerabilities[packageName] = selectVulnerabilityFields(
+      report.vulnerabilities[packageName],
+    );
+  }
+
+  return {
+    vulnerabilityCounts: report.metadata?.vulnerabilities,
+    vulnerabilities,
+  };
+}
+
+function cleanAuditResult(report) {
+  const counts = report.metadata?.vulnerabilities;
+  const vulnerabilities = report.vulnerabilities || {};
+  const zeroCounts = counts
+    && ['info', 'low', 'moderate', 'high', 'critical', 'total']
+      .every((key) => counts[key] === 0);
+  return zeroCounts && Object.keys(vulnerabilities).length === 0;
+}
+
+function validatePolicy(policy) {
+  assert.equal(policy?.schemaVersion, 1);
+  assert.ok(Array.isArray(policy.exceptions));
+  assert.equal(
+    policy.exceptions.length,
+    0,
+    'No npm audit exceptions are permitted',
+  );
+}
+
+function validateAuditReport(report, policy) {
+  if (
+    report
+    && typeof report === 'object'
+    && (
+      (report.error && typeof report.error === 'object')
+      || typeof report.message === 'string'
+    )
+  ) {
+    const detail = [
+      report.message,
+      report.error?.summary,
+      report.error?.detail,
+    ].find((value) => typeof value === 'string' && value.trim());
+    throw new Error(
+      `npm audit did not return an advisory report${detail ? `: ${detail.trim()}` : ''}`,
+    );
+  }
+  assert.equal(report?.auditReportVersion, 2, 'Unsupported npm audit report version');
+  validatePolicy(policy);
+
+  if (cleanAuditResult(report)) {
+    return {
+      allowedAdvisories: [],
+      propagatedVulnerabilities: [],
+    };
+  }
+  throw new Error(
+    'npm audit reported a vulnerability; Trackly CLI permits no audit exceptions.',
+  );
+}
+
+function loadPolicy(policyPath = DEFAULT_POLICY_PATH) {
+  return JSON.parse(fs.readFileSync(policyPath, 'utf8'));
+}
+
+function runAudit() {
+  const result = spawnSync(NPM, ['audit', '--json', '--audit-level=moderate'], {
+    cwd: path.join(__dirname, '..'),
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024,
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (!result.stdout.trim()) {
+    throw new Error(`npm audit returned no JSON. stderr: ${result.stderr.trim()}`);
+  }
+
+  let report;
+  try {
+    report = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new Error(
+      `npm audit returned invalid JSON. stderr: ${result.stderr.trim()}`,
+      { cause: error },
+    );
+  }
+
+  return validateAuditReport(report, loadPolicy());
+}
+
+if (require.main === module) {
+  try {
+    const result = runAudit();
+    if (result.allowedAdvisories.length === 0) {
+      console.log('npm audit is clean; no temporary exceptions were used.');
+    } else {
+      console.log(
+        `npm audit matches the single temporary exception: ${result.allowedAdvisories.join(', ')}`,
+      );
+    }
+  } catch (error) {
+    console.error(error.message);
+    if (error.cause?.message) {
+      console.error(error.cause.message);
+    }
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  loadPolicy,
+  normalizedAuditShape,
+  runAudit,
+  validateAuditReport,
+};

package/security/audit-exceptions.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "exceptions": []
+}

package/server.json

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

package/skills/trackly-apply/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trackly-apply
-description: Fill user-approved jobs from a Trackly apply/check-later queue through a supported ATS in a real browser, using the user’s profile and resume from Trackly, then stop for manual review and submission. Use for requests such as “apply to my queue,” “fill the next application,” “Trackly apply,” or “prepare job 123 for review” in Codex or Claude Code on macOS.
+description: Fill the next user-approved jobs from a Trackly apply/check-later queue through a supported ATS in a real browser, using the user’s profile and resume from Trackly, then stop for manual review and submission. Use for requests such as “apply to my queue,” “fill the next application,” or “Trackly apply” in Codex or Claude Code on macOS.
 ---
 
 # Trackly Apply
@@ -19,7 +19,13 @@ Use Trackly as the source of truth for profile answers, documents, queue decisio
 
 ## Start every run
 
-1. Call `trackly_get_apply_protocol`. Skill 4.1 requires protocol major 3 (version 3.1.0 or newer) and `compatibleSkillMajor: 4`. Reject an older or incompatible version and report that the backend must finish updating or `trackly agent setup` must update the skill. This gate prevents a pre-evidence skill or run from being reused under the stronger cross-ATS contract. Protocol 3.2 adds exact-origin trust for jobs Trackly ingested directly from employer careers sources; do not recreate the retired ownership-timestamp gate in the client.
+Before selecting or resuming work, read
+[references/batch-orchestration.md](references/batch-orchestration.md) and
+[references/browser-lifecycle.md](references/browser-lifecycle.md). Those
+references define the server-frozen batch, grouped-question, tab-reconciliation,
+and missing-surface recovery contract; they are mandatory even for a one-job batch.
+
+1. Call `trackly_get_apply_protocol`. Skill 4.2.2 requires protocol major 3 and protocol 3.3.1 or newer for frozen-batch execution; protocol 3.2 remains valid for the explicit legacy single-run workflow. Require `compatibleSkillMajor: 4` and `compatibleSkillMinimumVersion` no newer than this installed skill. Reject an older or incompatible version and report that the backend must finish updating or `trackly agent setup` must update the skill. Protocol 3.2 added exact-origin trust for jobs Trackly ingested directly from employer careers sources; do not recreate the retired ownership-timestamp gate in the client.
 2. Call `trackly_get_profile_onboarding` or fetch both the profile schema and application profile. Treat `completeness.percent` as required onboarding readiness only. Use `coverage.missingReusableKeys` to explain reusable optional gaps, while `coverage.contextualKeys` are intentionally asked only on the relevant employer form. Do not claim that 100% required completeness answers every possible application question.
 3. Save answers with `trackly_update_application_profile`:
    - Use `answered`, `intentionally_blank`, `declined`, or `unknown` exactly.
@@ -34,14 +40,15 @@ Use Trackly as the source of truth for profile answers, documents, queue decisio
    - Use `consent.future_opportunity_retention` only at company scope because one employer's optional retention choice is not consent for another employer.
    - Treat an accuracy or truthfulness certification as a live per-run attestation. Never save that attestation to the reusable profile; ask and verify it on every application run.
 4. Require the one-time profile confirmation, complete education entries, and default-resume metadata before browser work. Do not prepare or upload the resume when the form has no attachment control.
-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.
-   - Use the queue item's backend-owned `atsCapability`, `originPolicy`, and `executionBlocker`. Never infer a stronger support claim from the page design or the LLM's familiarity with a provider. Required scenarios are backend-enforced gates; possible scenarios are reported only when actually exercised.
-   - Stop before `trackly_start_apply_run` whenever `executionBlocker` is non-null. `standard` runs use the provider playbook. `guided` runs are allowed only while semantic browser state remains observable, `originPolicy.authorized` is true, and every published stop condition is obeyed. `manual_only` items stop without starting or mutating a run.
+5. For every protocol 3.3.1 request, call `trackly_get_active_apply_batch` before creating anything. When it returns a batch, page and resume that exact batch, including every non-null existing member `runId`; never replace it because chat context, a tab, or the local ledger was lost. Only when it returns no active batch may you call `trackly_create_apply_batch` once with the requested count and a fresh idempotency key. Then page only that batch with `trackly_get_apply_batch` and claim it with `trackly_claim_apply_batch`. The returned server membership and order are authoritative. Do not call `trackly_get_apply_queue` first to construct a client-side candidate list; reserve that tool for previewing the queue or resuming a legacy protocol 3.2 single run.
+   - Use the frozen member's `staticExclusionCode` as the pre-run blocker. Never infer a stronger support claim from the page design or the LLM's familiarity with a provider. For a member without a static exclusion, call `trackly_start_apply_run`; its returned backend-owned `atsCapability`, `originPolicy`, `executionBlocker`, and required scenarios are authoritative for browser work.
+   - Stop after `trackly_start_apply_run` whenever its `executionBlocker` is non-null. `standard` runs use the provider playbook. `guided` runs are allowed only while semantic browser state remains observable, `originPolicy.authorized` is true, and every published stop condition is obeyed. `manual_only` items stop without browser or private-data mutation.
    - When `originPolicy.verification` is `trackly_employer_source_exact_origin`, Trackly has authorized the exact stored HTTPS origin from its direct employer-careers ingestion. Do not demand a separate ownership timestamp, ATS tenant, or company-domain suffix. This authorization never extends to another origin, hostname suffix, redirect, or iframe. The queue/run will require `job_identity_match`; pass it only after the browser visibly confirms the frozen company, role, and available requisition identity. Revalidate that identity after every navigation or redirect and before entering any additional private data.
-   - If the user requests the next `N` jobs, freeze the deterministic ordered set of exactly `N` job IDs before starting any run. Do not replace, rescore, or expand that approved batch.
+   - If the user requests the next `N` jobs, freeze up to `N` available saved jobs before starting any run. Preserve inactive, insecure, or protocol-declared manual-only members with their static exclusion reason; do not replenish, replace, rescore, or expand the batch. If fewer than `N` saved jobs exist, report the frozen count rather than searching for substitutes.
    - For each fixed batch member, preserve an explicit job ID -> application run ID -> browser tab mapping. Complete the full start -> conditional resume preparation/confirmation/verification when an upload control exists -> form completion -> `review_ready` lifecycle for every member. A review-ready run does not block the next member. Never submit any of them.
-6. Call `trackly_start_apply_run` for the selected job or current fixed batch member. Reuse an active run returned by Trackly; never create a replacement run because browser control was interrupted.
-   - Require `run.protocolVersion` to be 3.1.0 or newer and to share protocol major 3 with the fetched protocol. Never continue a pre-evidence 3.0.x run under skill 4.1. Preserve that run instead of starting a replacement, record it `blocked` with a value-free protocol-upgrade reason when possible, and tell the user the saved job can be retried only after the stale run is cleared through Trackly's supported lifecycle. Compare `run.atsCapability` and `run.originPolicy` with the queue values. Stop and refetch the protocol and queue if support level, execution mode, provider, required scenarios, or authorized origin policy changed between preflight and run creation.
+6. Call `trackly_start_apply_run` for the selected job or current fixed batch member with the complete `batchId`, `memberId`, `expectedMemberVersion`, `expectedInspectionEpoch`, and `leaseToken` returned by Trackly. This call is also the sanctioned idempotent lookup when a recovered member has no `runId`; call it with the exact recovered binding and Trackly will reuse the bound active run. Never create a replacement run because browser control was interrupted.
+   - If a bound start returns a transport failure, a non-access HTTP 5xx response, or an error explicitly marked `retryable: true`, preserve the frozen member and browser state. Refetch the active batch, renew its lease, and retry the same complete binding once. Classify the retry response independently with these same rules: route canonical `maintenance_mode` or legacy `planned_maintenance` directly through **Resume after maintenance**; surface controlled-access/request errors marked `retryable: false` and every other HTTP 4xx response unchanged; only a second transport failure, non-access HTTP 5xx response, or explicitly retryable error becomes `backend_run_start_unavailable`. Route maintenance on either attempt without consuming or relabeling the retry, and never relabel a permanent retry response as an outage. For `backend_run_start_unavailable`, continue other members and report a Trackly control-plane failure. Do not call `trackly_checkpoint_apply_batch` for this condition because start failure has not produced the required run ID. The unchanged frozen member is the durable resume point. Never switch that frozen member to an unbound legacy run or blame the employer form.
+   - Require `run.protocolVersion` to be 3.1.0 or newer and to share protocol major 3 with the fetched protocol. A new batch member requires 3.3.1 or newer; an explicit 3.2 single run may start or finish through its legacy path. Never continue a pre-evidence 3.0.x run under skill 4.2.2. Preserve that run instead of starting a replacement, record it `blocked` with a value-free protocol-upgrade reason when possible, and tell the user the saved job can be retried only after the stale run is cleared through Trackly's supported lifecycle. Stop and refetch the protocol and active batch if support level, execution mode, provider, required scenarios, authorized origin policy, member version, or inspection epoch changes after run creation.
    - In guided mode, inspect the page before preparing any resume bytes. Confirm the employer, role, HTTPS origin, reachable review path, semantic controls, whether an attachment control exists, and absence of a credential, verification, CAPTCHA, or submit-only wall. A missing file input is not itself a blocker; skip the resume path when the application has no attachment control. Any other failed precondition is an execution blocker, not permission to improvise.
 7. Pass the browser readiness gate before preparing resume bytes:
    - Use semantic browser control through Codex in-app browser controls, Chrome MCP/extension browser control, or Claude in Chrome.
@@ -49,25 +56,25 @@ Use Trackly as the source of truth for profile answers, documents, queue decisio
    - Bind each tab to the exact employer, role, ATS, requisition URL, job ID, and run ID. A window position or ephemeral tab number alone is not identity.
    - Build a value-free browser binding from those normalized keys plus the semantic browser surface and stable controller tab identity. Compute its lowercase SHA-256; never send the raw URL, title, employer, role, or tab text as observation metadata.
    - After a handoff, context resume, or browser-control interruption, reclaim and re-verify every mapped tab before continuing.
-   - Report `observationType: browser_ready` for the current run with `scenarioCode: browser_reclaim`, the allowed `browserSurface`, `committed: true`, and that `browserBindingHash`. Do not call `trackly_prepare_resume` until this same-run attestation succeeds. Accessibility may provide an independent verification signal, but coordinate-only clicking is forbidden for form completion.
+   - Report `observationType: browser_ready` for the current run with the exact current `batchId`, `memberId`, and `inspectionEpoch`, plus `scenarioCode: browser_reclaim`, the allowed `browserSurface`, `committed: true`, and that `browserBindingHash`. Do not call `trackly_prepare_resume` until this same-run attestation succeeds. Accessibility may provide an independent verification signal, but coordinate-only clicking is forbidden for form completion.
    - If the semantic browser bridge is unavailable, preserve every existing run and tab mapping, record the blocker when possible, and stop before any upload or form mutation.
 8. If and only if the application offers or requires a resume attachment, call `trackly_prepare_resume` with that exact application run ID, browser surface, and browser binding hash. If hosted MCP reports it unavailable, tell the user that local Trackly MCP or manual upload is required. If no attachment control exists, skip steps 8–11 and do not report `resume_upload` as exercised.
 9. 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.
 10. 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.
+   - Show a compact local proof block with source (`Trackly default resume`), exact local path, user-facing filename, file size, SHA-256 fingerprint, application run, and expiration. The exact path is local-only. The SHA-256 may be sent only to Trackly's authenticated resume approval, prepared-resume verification, and truth-certification tools; never send either value in observations, logs, application answers, analytics, or employer form fields.
    - Ask for explicit confirmation to use that resume. Bind confirmation to the exact SHA-256 and current application run. For an explicitly approved batch of `N` runs, the user may authorize the same confirmed SHA-256 only for the frozen job/run/tab set; still show and verify each member's exact path, size, hash, run ID, and expiration. Stop if any hash differs, a run is missing, or a run falls outside the frozen batch. Outside that batch, 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.
-11. 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.
+11. After the user confirms and immediately before attachment, call local `trackly_verify_prepared_resume` with the confirmed run ID, resume 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
 
 If any REST or MCP tool returns canonical `maintenance_mode` (or the legacy `planned_maintenance` compatibility alias):
 
-1. Retain the current `agent_browser` run ID, selected job, and browser context. Do not call `trackly_start_apply_run` again.
+1. Retain the current `agent_browser` run ID, selected job, and browser context. Do not blindly call `trackly_start_apply_run` while maintenance is active. After recovery, call it only when the active frozen member omits `runId`, using the exact current member/version/epoch/lease binding so Trackly performs the sanctioned idempotent lookup.
 2. Stop issuing mutations and wait for the advertised retry window or estimated return time. Do not loop or blindly retry.
 3. After maintenance clears, refetch `trackly_get_apply_protocol` and the application profile/onboarding state before taking another action.
 4. Resume the existing run from the observable browser state, re-verify fields that may have rerendered, and continue toward manual review.
@@ -85,13 +92,13 @@ Follow this order:
 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. Resolve boolean values by their exact semantic label (`true` to Yes, `false` to No), never by option order, index, proximity, or a stale prior selection. After every selection, compare the committed value with the canonical Trackly value. If the field is required or had a validation error before selection, verify that the required-field error disappeared. An optional control with no validation error passes when its committed value is correct. Treat any value mismatch or applicable stale error as a failed field and correct it before continuing.
 6. Recheck email and phone through both browser DOM state and macOS accessibility state. Require exact values and reject duplicate/concatenated values.
-7. Complete known optional fields, education, links, relocation, and source answers. Do not silently omit canonical answers.
+7. Complete every visible field whose canonical answer is known, including optional fields, previous-employer/title history, education rows and dates, links, relocation, communication preferences, and opportunity source. Before review, compare the live field inventory with the resolved Trackly profile and prove that no known visible answer was silently omitted. Group only genuinely unknown contextual fields into the question packet.
    - Treat partial dates as unknown at the missing precision. If Trackly has only a year but the ATS requires a month, ask once and sync the complete date before selecting either control. Never accept an ATS-selected current/default month or infer an education month.
 8. Use the canonical `consent.background_check_if_advanced` field only when the form explicitly asks for consent to a background check if the candidate advances. If it is unknown, ask before selecting it and save the answer at the user's chosen scope. Never infer it from privacy, demographic, recruiting-data, general application, criminal-record, or professional-reference consent. Treat the latter two as separate unknown consent questions unless the current profile schema supplies their own canonical fields.
 9. For a free-text application response, read [references/application-writing.md](references/application-writing.md). Calibrate from the user's Trackly writing fields, use only supported profile and role facts, and run the built-in voice and anti-slop gate before entering the response. Do not require a separate writing or humanizer skill.
 10. Run the full integrity gate, including the final consent checkbox, every visible error, all steps, and any correction banner.
 
-When the user corrects an answer, immediately save the appropriate scope with `trackly_update_application_profile` and report only a redacted mechanics observation through `trackly_report_apply_observation`. Never promote one user’s value into a global default. For `generic_web_form`, never save provider-scoped answers; use company scope for form-specific answers.
+When the user corrects an answer, immediately save the appropriate scope with `trackly_update_application_profile` and report only a redacted mechanics observation. For a frozen batch, collect current-epoch evidence locally and send it through `trackly_report_apply_observations` in one bounded bulk call; use `trackly_report_apply_observation` only for a legacy single run or an isolated follow-up. For every protocol 3.3 observation, include the exact current `batchId`, `memberId`, and `inspectionEpoch`; stale-epoch evidence must fail closed and be recreated only after reclaiming the current surface. Never promote one user’s value into a global default. For `generic_web_form`, never save provider-scoped answers; use company scope for form-specific answers.
 
 For every run, track only scenarios actually exercised, except the two universal review proofs below. Attest `browser_reclaim` once with the same-run `observationType: browser_ready`, exact binding hash, browser surface, and `metadata.committed: true`; do not send a duplicate `scenario_coverage` row for it. Before `review_ready`, report every other exercised scenario with `observationType: scenario_coverage`, the stable scenario code, browser surface, `metadata.committed: true` for `passed` or `corrected`, and whether the tab was resumed after handoff.
 
@@ -105,12 +112,14 @@ Every required scenario and both universal evidence scenarios must have correspo
 
 ## Review handoff
 
-Call `trackly_record_application_outcome` with `review_ready`, then provide the review block defined in [references/review-handoff.md](references/review-handoff.md). For a single run, keep the browser on the final review state and stop. For a frozen batch, preserve the current review-ready tab and continue the same lifecycle for the next mapped batch member; stop only after every frozen member is review-ready, then provide one review block per run. Never submit any member. End with job ID -> run ID -> browser tab -> ATS -> status plus the actual scenario coverage for each run.
+After every conditional field is settled and all other review gates pass, bulk checkpoint every ready member with `review/manual_submit`, the current unchanged inspection epoch in both epoch fields, and any `resolvedActionIds`. Use the returned member versions and epochs; this checkpoint resolves the listed human actions and moves the durable member lifecycle to `review_ready` without invalidating current-epoch browser evidence or an unchanged resume-content approval. Do not wait for `needs_input` members: whenever at least one member is durably `review_ready`, ask for one explicit final truthfulness confirmation for the exact complete subset that is currently `review_ready`. If any form in that certified subset used a resume attachment, certify with `resumeDependency: approved` and the exact approved resume identity. If no form in the subset exposes a resume control, certify with `resumeDependency: not_applicable` and omit the resume ID and hash; do not invent an upload requirement. Then call `trackly_record_application_outcomes` once with every member in that certified subset using its exact current `runId`, `batchId`, `memberId`, `inspectionEpoch`, and `leaseToken`; refresh only members returned as conflicts. A member that becomes ready later requires a fresh certification for the then-current complete `review_ready` subset; never reuse an older certification for it. Use singular `trackly_record_application_outcome` only for a legacy single run or an isolated post-review transition. Provide the review block defined in [references/review-handoff.md](references/review-handoff.md). For a single run, keep the browser on the final review state and stop. For a frozen batch, preserve every review-ready tab, hand off each certified review-ready subset without waiting on unrelated human actions, and continue the same lifecycle for the remaining mapped members. Members with unresolved actions stay frozen and resumable. Never submit any member. End with job ID -> run ID -> browser tab -> ATS -> status plus the actual scenario coverage for each run.
 
 After the user submits manually:
 
-- If a success page is visible, record `submitted` with a short non-sensitive confirmation signal.
-- If the user explicitly confirms submission, record `submitted` with `user_confirmed`.
+- If a success page is visible, reclaim the current batch lease if needed, first record current-epoch `confirmation_detected` evidence with source `success_page` through `trackly_record_apply_submission_evidence`, then record `submitted` with the exact current batch/member/epoch/lease binding and confirmation `success_page`.
+- If the user explicitly confirms submission, reclaim the current batch lease if needed, first record current-epoch `confirmation_detected` evidence with source `user_confirmation` through `trackly_record_apply_submission_evidence`, then record `submitted` with the exact current batch/member/epoch/lease binding and confirmation `user_confirmation`.
+- Treat the outcome response as a durable commit gate. Refetch each submitted member and require both member lifecycle `submitted` and Trackly job state `applied_confirmed`. On conflict, preserve the success tab, refresh once, and replay only the documented idempotent evidence/outcome sequence. If reconciliation still fails, report a P0 reconciliation defect and leave the tab open; never claim Trackly moved the job.
+- A provider receipt is optional orthogonal evidence. Record it as `provider_receipt_detected`; never use `provider_receipt` as the outcome confirmation or as a substitute for a success page or explicit user confirmation.
 - If neither exists, do not move the job to applied.
 - Treat a contradictory ATS response such as “already applied” as provisional until the exact requisition URL settles. Do not click Submit again. Preserve the page, confirm the job/requisition identifier is unchanged, and re-read the final route state after the UI and network activity settle. A later explicit success state on that same requisition overrides the provisional error and must be recorded as `submitted`; otherwise record the run as blocked without marking the job applied.
 

package/skills/trackly-apply/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Trackly Apply"
   short_description: "Fill queued job applications for manual review"
-  default_prompt: "Use $trackly-apply to fill my next approved Trackly job application and stop before Submit."
+  default_prompt: "Use $trackly-apply. Resume my active frozen batch, or create a one-job batch from my next approved Trackly job. Keep the browser visible, verify every committed field, and stop before Submit."

package/skills/trackly-apply/references/ats-playbook.md

@@ -4,6 +4,8 @@
 
 - Accept employer-hosted Greenhouse forms and `job-boards.greenhouse.io` / `boards.greenhouse.io` application hosts after matching the employer and role.
 - Expect resume parsing, React selects, correction banners, demographic sections, and final consent checkboxes.
+- Use the visible file chooser or its semantic file input; never click a nearby decorative upload region by coordinates.
+- For custom selects and checkbox groups, verify the selected label or checked element in the live DOM after the real click. A displayed answer with a remaining required error is uncommitted.
 - Treat red required-field text as authoritative even when a value is visible.
 - A Greenhouse “Thank you for applying” page is a valid submission signal.
 
@@ -11,6 +13,9 @@
 
 - Accept `jobs.ashbyhq.com` only after matching the employer and role.
 - Expect rerenders, masked contact inputs, and controls whose visible text can differ from committed state.
+- Resolve binary button groups by the live selected/active state and semantic Yes/No label, never by button order or styling alone.
+- Treat education as repeatable structured rows. After activating `+ Add Education`, require the row count to increase before filling the new row. If Playwright reports a click but the submit-typed control does not add a row, retry with the visible semantic DOM control; stop if the row remains absent.
+- Select localized school suggestions by the exact intended institution and then verify the committed row value.
 - Best effort: stop when browser and accessibility state disagree.
 - An explicit application-success banner/page is a valid submission signal.
 
@@ -37,6 +42,7 @@ This group includes SmartRecruiters, Workable, BambooHR, Recruitee, Jobvite, Tea
 - Expect a mixture of native controls, custom widgets, employer subdomains, embedded frames, shared profile data, and optional resume parsing.
 - Match the live HTTPS origin, employer, role, and requisition before entering private data.
 - Use the same committed-state and required-error gate as Greenhouse. Familiar-looking controls do not lower the evidence requirement.
+- On HiBob, treat document upload as a two-step commit when the UI requires choosing the file and then confirming the upload. Verify the final filename/attachment state; a selected local file alone is not an attached resume.
 
 ## Unknown employer-hosted form
 

package/skills/trackly-apply/references/batch-orchestration.md

@@ -0,0 +1,208 @@
+# Batch orchestration
+
+Use the backend batch contract for every new protocol 3.3 run, including a
+one-job request. The batch is an execution ledger, not a fit-ranking exercise.
+Protocol 3.2 is retained for the explicit legacy single-run workflow.
+
+## Freeze before browser work
+
+Create one server-frozen batch before opening or mutating application forms.
+Use the backend order exactly: active jobs first, then `savedAt` descending,
+then job ID ascending. Never replace, rescore, or expand frozen membership
+because a form is difficult or another job looks easier. A job saved after the
+snapshot belongs only to a future batch.
+
+Static planning keeps an inactive posting, insecure URL, or protocol-declared
+manual-only job in frozen membership with a non-executable exclusion reason.
+Never replenish or replace it with another queued job. Credentials, CAPTCHA
+placement, attachment controls, semantic observability, and review reachability
+are browser findings; they do not change membership. If the user removes or
+discards a frozen member, stop before its next private-data mutation.
+
+Read large batches through opaque continuation tokens. Do not recreate ordering
+or pagination in the prompt.
+
+## Backend tool sequence
+
+For every protocol 3.3.1 request:
+
+1. call `trackly_get_active_apply_batch` before any create call;
+2. resume the returned active batch, or, only when none exists, call
+   `trackly_create_apply_batch` once with the requested size and a fresh
+   idempotency key;
+3. page only that batch with `trackly_get_apply_batch`;
+4. acquire or renew ownership with `trackly_claim_apply_batch`;
+5. start or reuse each run with the complete batch/member/lease binding; and
+6. send browser findings in groups of at most 20 through
+   `trackly_checkpoint_apply_batch`.
+
+Do not recreate a batch after maintenance. Refetch the existing batch, reclaim
+its lease with the latest revision, and resume its existing run bindings.
+When a bound run start returns a transport failure, a non-access HTTP 5xx
+response, or an error explicitly marked `retryable: true`, refetch and renew,
+then retry the same complete binding once. Classify the retry response
+independently with the same rules. Route `maintenance_mode` or the legacy
+`planned_maintenance` alias from either attempt through maintenance recovery.
+Surface controlled-access/request errors marked `retryable: false` and every
+other HTTP 4xx response unchanged, including when returned by the retry. Only a
+second transport failure, non-access HTTP 5xx response, or explicitly
+retryable error becomes `backend_run_start_unavailable` while siblings
+continue. Do not checkpoint this condition: no run ID exists yet, and the
+checkpoint contract requires one. The unchanged frozen member is the durable
+resume point. Never detach that member into a legacy single run.
+
+### Request budget
+
+For a failure-free new 20-member batch, keep planning, initial binding, evidence,
+two bulk checkpoints, resume approval, truth certification, outcomes, and the
+final batch refresh within 52 non-resume MCP/HTTP requests: one active-batch
+lookup, one create, one page, one claim, 20 run starts, 20 surface bindings, one
+`trackly_report_apply_observations` call before resume preparation, a second
+bulk observation call for final scenario coverage, two bulk checkpoints, one
+resume approval, one truth certification, one
+`trackly_record_application_outcomes` call, and one final refresh. An existing
+active batch omits the create call. Do not replace bulk observations,
+checkpoints, or outcomes with per-member requests. Resume download and exact
+local verification are excluded from this count. Each member that encounters
+the one permitted retryable bound-start failure receives exactly three
+additional recovery calls: refetch the active batch, renew its lease, and retry
+the same binding. Therefore the bounded contingency budget is `52 + (3 * R)`,
+where `R` is the number of affected members and cannot exceed 20. Maintenance
+recovery is paced by the advertised window and is tracked separately.
+
+## Ownership and replay safety
+
+Acquire the renewable lease before browser mutation. Each mutation supplies
+only the guards exposed by its tool schema: lease token when the schema exposes
+it, optimistic version when the schema exposes it, inspection epoch when the
+schema exposes it, and idempotency key when the schema exposes it. Never invent
+or attach an uncontracted guard.
+
+Renew before expiry and stop mutation if ownership is lost. For operations
+documented as idempotent, a same-key, same-payload replay returns the original
+result. A same key with a different payload is a conflict (`409`), never
+permission to retry under a new run. Do not blindly retry a mutation without an
+idempotency key after an ambiguous response; recover through the documented
+read or lookup operation first. Reclaiming a browser tab increments the
+inspection epoch; earlier-epoch review, attachment, certification, or close
+evidence cannot satisfy the current gate.
+
+## First pass
+
+Process every frozen member even when another needs user input:
+
+1. Create or reuse its bound application run.
+2. Reclaim or open its exact stored requisition URL and validate origin and job
+   identity.
+3. Inventory the accessible form.
+4. Fill and verify every known field before checkpointing an unknown.
+5. Record typed human actions and continue to the next frozen member.
+
+Recoverable actions keep the run in `needs_input`. Group the first interruption
+into one grouped first-pass packet organized by company, role, run, and action
+type. After answers reveal conditional fields, send a delta packet containing
+only newly revealed items.
+
+Action records contain only value-free type, stage, blocking scope,
+continuation flags, status, and redacted fingerprints. Credentials, OTPs,
+CAPTCHA answers, raw question text, and private answer values never enter
+Trackly observations.
+
+Each checkpoint includes the expected member version, unchanged current
+inspection epoch in both epoch fields, lease token, one to 25 typed actions, the shared
+known-fields-committed flag, optional packet phase, and its own idempotency key.
+Each action carries its continuation flag and optional redacted field
+fingerprint. All actions in one checkpoint share one member lifecycle. The
+member version advances once, but only a browser bind or reclaim may advance the
+inspection epoch. Never add raw labels, options, answers, or page text to this
+packet.
+
+Use `packetPhase: first_pass` while inventorying the frozen set. Use
+`packetPhase: delta` only for a conditional question or action that became
+visible after the first grouped packet. A per-member conflict does not cancel
+successful siblings; refresh only the conflicted member before retrying it.
+When the user has completed or answered a prior human action, include its exact
+server-returned ID in `resolvedActionIds` on the next checkpoint for that same
+member and current inspection epoch. Never infer, fabricate, or resolve an
+action from another member; an unknown or stale action ID must conflict.
+
+## Challenge placement
+
+An access CAPTCHA or verification wall that hides the semantic form must be
+recorded before private data is entered. Create a human action and continue the
+batch.
+
+A submit-time CAPTCHA beside an otherwise complete final form stays
+`review_ready` with an `at_submit` human action because the user owns Submit.
+Never solve, store, or bypass the challenge. Reserve terminal `blocked` for an
+unrecoverable trust or observability failure, not for an answer the user can
+provide.
+
+## Resume approval and truth
+
+Resume approval is early and content-bound. It covers only immutable batch/run
+membership, default-resume identity, exact content hash, user-facing filename,
+size, profile revision, and expiry. Each upload still needs its own immediate
+per-run local path proof for the exact bytes.
+
+Exact local paths are user-visible local proof only and never leave the
+machine. Content hashes may be sent only to authenticated Trackly resume
+approval, prepared-resume verification, and truth-certification endpoints.
+Never send either value to observations, application answers, analytics, logs,
+or employer form fields.
+
+Prepare the resume for every run that exposes a real Resume or CV control. Show
+one consolidated proof with every run/path plus the shared resume identity,
+filename, size, and SHA-256. After explicit user approval, call
+`trackly_approve_apply_batch_resume` for the complete current run set. Reuse that
+content approval only while every returned immutable dependency remains exact.
+Ordinary checkpoints may advance member versions without invalidating approval
+for unchanged resume bytes and run membership. Immediately before each
+attachment, call `trackly_verify_prepared_resume` with that run's resume ID and
+signed local proof.
+
+Truth certification is late. Ask only after final answers and any conditional
+wording are known. Bind it to the run set, answer snapshot, wording
+fingerprints, profile revision, inspection epochs, and expiry. When at least
+one form used a resume attachment, use `resumeDependency: approved` and bind
+the exact approved resume identity. When no form in the batch exposes a resume
+control, use `resumeDependency: not_applicable` with no resume ID or hash. It
+is ephemeral evidence and never a reusable profile answer.
+
+After all conditional questions and certification wording are visible, show one
+final truthfulness prompt. Only after explicit user confirmation, compute the
+value-free answer-snapshot and wording fingerprints and call
+`trackly_certify_apply_batch_truth` for the exact complete subset that is
+currently `review_ready`. A `needs_input` member does not block certification
+or handoff of ready siblings. Never certify an arbitrary subset. When another
+member becomes ready later, obtain a fresh certification for the then-current
+complete `review_ready` subset. Never place the certification or its wording in
+the application profile.
+
+A membership, profile revision, resume identity or hash, answer snapshot,
+certification wording, or affected inspection epoch change invalidates the
+affected approval or attestation. An ordinary member-version checkpoint does
+not invalidate an unchanged resume-content approval. Recompute and ask again
+only for the invalidated scope.
+
+## Finish
+
+Bring every accessible member to `review_ready`, preserving each browser tab
+for manual submission. Certify, record, and hand off the exact current
+`review_ready` subset without waiting for unrelated members. Members with
+actions remain frozen and resumable, and require a fresh certification after
+they later become ready. Report one compact table mapping job ID, run ID,
+browser surface/tab label, ATS, state, actions, and evidence status. Raw tab
+identifiers stay local.
+
+Never submit a member. After manual submission, mark Applied only from an
+observable success page or explicit user confirmation. Record the submit
+request, success page or `user_confirmation`, and any provider receipt with
+`trackly_record_apply_submission_evidence`; store only the redacted fingerprint
+and typed source. The outcome call is not complete until a fresh batch read
+shows member lifecycle `submitted` and tracker state `applied_confirmed`.
+Preserve the success tab during one documented idempotent conflict recovery;
+if reconciliation remains unsuccessful, report the control-plane defect and
+do not claim completion. Only then reconcile tab closure separately using the
+browser-lifecycle gate. Submission, durable outcome, receipt, and closure never
+substitute for one another.