trackly-cli 0.7.2 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.7.2",
+  "version": "0.8.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": {
@@ -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"

package/scripts/verify-audit-exceptions.js

@@ -0,0 +1,190 @@
+#!/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,
+    1,
+    'Exactly one temporary npm audit exception is permitted',
+  );
+  const exception = policy.exceptions[0];
+  assert.equal(exception.advisory, 'GHSA-frvp-7c67-39w9');
+  assert.equal(exception.package, '@hono/node-server');
+  assert.equal(exception.dependencyOf, '@modelcontextprotocol/sdk');
+  assert.equal(exception.severity, 'moderate');
+  assert.equal(exception.vulnerableRange, '<2.0.5');
+  assert.equal(
+    exception.upstream,
+    'https://github.com/modelcontextprotocol/typescript-sdk/issues/2531',
+  );
+  assert.ok(exception.expectedAuditShape);
+  return exception;
+}
+
+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');
+  const exception = validatePolicy(policy);
+
+  if (cleanAuditResult(report)) {
+    return {
+      allowedAdvisories: [],
+      propagatedVulnerabilities: [],
+    };
+  }
+
+  try {
+    assert.deepEqual(normalizedAuditShape(report), exception.expectedAuditShape);
+  } catch (error) {
+    const wrapped = new Error(
+      'npm audit report does not match the temporary exception. '
+      + 'Review every new advisory, severity, affected range, and dependency-path change.',
+    );
+    wrapped.cause = error;
+    throw wrapped;
+  }
+
+  return {
+    allowedAdvisories: [exception.advisory],
+    propagatedVulnerabilities: Object.keys(report.vulnerabilities).sort(),
+  };
+}
+
+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,70 @@
+{
+  "schemaVersion": 1,
+  "exceptions": [
+    {
+      "advisory": "GHSA-frvp-7c67-39w9",
+      "source": 1124006,
+      "package": "@hono/node-server",
+      "dependencyOf": "@modelcontextprotocol/sdk",
+      "severity": "moderate",
+      "vulnerableRange": "<2.0.5",
+      "upstream": "https://github.com/modelcontextprotocol/typescript-sdk/issues/2531",
+      "rationale": "Trackly starts the MCP SDK only through its stdio transport. It does not import @hono/node-server, Streamable HTTP, or serveStatic, so the Windows static-file path traversal is unreachable. Automated stdio isolation and packed-consumer tests enforce that boundary until the SDK removes or upgrades this dependency.",
+      "expectedAuditShape": {
+        "vulnerabilityCounts": {
+          "info": 0,
+          "low": 0,
+          "moderate": 2,
+          "high": 0,
+          "critical": 0,
+          "total": 2
+        },
+        "vulnerabilities": {
+          "@hono/node-server": {
+            "name": "@hono/node-server",
+            "severity": "moderate",
+            "isDirect": false,
+            "via": [
+              {
+                "source": 1124006,
+                "name": "@hono/node-server",
+                "dependency": "@hono/node-server",
+                "title": "Node.js Adapter for Hono: Path traversal in `serve-static` on Windows via encoded backslash (`%5C`)",
+                "url": "https://github.com/advisories/GHSA-frvp-7c67-39w9",
+                "severity": "moderate",
+                "cwe": [
+                  "CWE-22"
+                ],
+                "cvss": {
+                  "score": 5.9,
+                  "vectorString": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:N/A:N"
+                },
+                "range": "<2.0.5"
+              }
+            ],
+            "effects": [
+              "@modelcontextprotocol/sdk"
+            ],
+            "range": "<2.0.5",
+            "nodes": [
+              "node_modules/@hono/node-server"
+            ]
+          },
+          "@modelcontextprotocol/sdk": {
+            "name": "@modelcontextprotocol/sdk",
+            "severity": "moderate",
+            "isDirect": true,
+            "via": [
+              "@hono/node-server"
+            ],
+            "effects": [],
+            "range": ">=1.25.0",
+            "nodes": [
+              "node_modules/@modelcontextprotocol/sdk"
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/server.json

@@ -17,12 +17,12 @@
       ]
     }
   ],
-  "version": "0.7.2",
+  "version": "0.8.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.7.2",
+      "version": "0.8.1",
       "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.1 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,14 @@ 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.
+   - 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.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. 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 +55,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.
@@ -91,7 +97,7 @@ Follow this order:
 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 +111,13 @@ 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`.
+- 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/batch-orchestration.md

@@ -0,0 +1,187 @@
+# 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.
+
+### Request budget
+
+For a new 20-member batch, keep recovery, 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.
+
+## 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. Then reconcile tab closure separately using the
+browser-lifecycle gate. Submission, receipt, and closure never substitute for
+one another.