trackly-cli 0.14.0 → 0.14.2

package/README.md

@@ -1,6 +1,6 @@
 [![npm](https://img.shields.io/npm/v/trackly-cli.svg)](https://www.npmjs.com/package/trackly-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node 20+](https://img.shields.io/badge/node-20+-brightgreen.svg)](https://nodejs.org/)
+[![Node 20.20+ or 22.22+](https://img.shields.io/badge/node-20.20%2B%20%7C%2022.22%2B-brightgreen.svg)](https://nodejs.org/)
 [![MCP Server](https://img.shields.io/badge/MCP-Server-blue.svg)](https://modelcontextprotocol.io/)
 
 # trackly-cli
@@ -31,11 +31,11 @@ trackly login
 trackly jobs --function product
 ```
 
-> **Prerequisites:** [Node.js 20+](https://nodejs.org/) (LTS recommended). On macOS with the official `.pkg` installer, global npm installs may require `sudo`.
+> **Prerequisites:** [Node.js 20.20+ or 22.22+](https://nodejs.org/) (LTS recommended). On macOS with the official `.pkg` installer, global npm installs may require `sudo`.
 
 ## At a Glance
 
-3,800+ companies | 170K+ jobs | 40+ ATS types | CLI + MCP | 54 local MCP tools
+3,800+ companies | 170K+ jobs | 40+ ATS types | CLI + MCP | 55 local MCP tools
 
 ## CLI Commands
 
@@ -215,6 +215,7 @@ Then use natural language in any of these clients:
 | trackly_record_application_outcomes | Bulk-record up to 20 leased batch outcomes with per-member conflicts |
 | trackly_prepare_resume | Prepare a private expiring resume file for upload |
 | trackly_verify_prepared_resume | Recheck the confirmed resume immediately before attachment |
+| get_more_tools | Report a missing capability so Trackly can improve its MCP surface |
 
 ## Authentication
 
@@ -280,7 +281,7 @@ trackly config --base-url http://127.0.0.1:3000  # Point at a different backend
 | Job search + filters | Yes | Yes | Yes |
 | Apply/save/dismiss | Yes | Yes | Yes |
 | AI-powered search | Yes (trackly ask) | Yes | Yes |
-| MCP integration | Yes (54 local tools) | -- | -- |
+| MCP integration | Yes (55 local tools) | -- | -- |
 | Browser required | No | Yes | No |
 | Best for | Terminal + AI agents | Visual browsing | Custom integrations |
 
@@ -294,7 +295,18 @@ Install trackly-cli (`npm install -g trackly-cli`), authenticate with `trackly l
 
 **What MCP servers exist for job searching?**
 
-trackly-cli includes a built-in MCP server with 54 tools for job search, company lookup, discovery preferences, application tracking, accessible execution and frozen-batch orchestration, profile onboarding, beta evidence, and manual-submit form preparation. Run `trackly mcp` or use `trackly agent setup --client claude`.
+trackly-cli includes a built-in MCP server with 55 tools: the complete Trackly
+job-search and application set plus `get_more_tools`, which lets agents report
+a missing capability. Run `trackly mcp` or use
+`trackly agent setup --client claude`.
+
+MCP usage analytics are on by default and relay through Trackly so the free
+service can be debugged and improved. They exclude résumé text, profile answers,
+demographic or work-authorization answers, and application notes. Turn off future
+collection with **Share usage analytics** in Account Settings. Operators may also
+disable local MCP instrumentation with `TRACKLY_MCP_ANALYTICS_DISABLED=1` (or
+`TRACKLY_MCP_ANALYTICS_ENABLED=0`); the account setting remains authoritative
+for authenticated backend capture.
 
 **How do I use Claude Code for job hunting?**
 

package/bin/trackly

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

package/docs/plans/2026-08-05-001-trackly-apply-durable-recovery-reconciliation-plan.md

@@ -49,9 +49,9 @@ None of these receipts implies another.
 - R1. Trackly must persist one cumulative completion credit per execution candidate after the candidate first reaches durable manual review or a valid submitted-state repair.
 - R2. A credited candidate must continue counting after manual submission; submitting it must not create replacement capacity.
 - R3. Execution status, raw cumulative achievement count, target-capped `completed`, current ready/submitted counts, reservations, `targetReached`, and `nextAction` must come from one transactionally consistent state.
-- R4. Trackly must recover an exact set of eligible members from one prior terminal or expired execution without changing queue recency or selecting newer jobs.
-- R5. Exact recovery must assert the requested source membership, report each member's eligibility, create no substitutes, reuse valid run identity, and require a fresh browser binding and inspection epoch.
-- R6. Exact recovery must reject foreign-user, revoked, changed-requisition, duplicate, and concurrently owned members. Already-applied members are reconciliation-only and inactive or access-blocked members remain typed non-counting dispositions.
+- R4. Trackly must recover the exact confirmed set from one prior terminal or expired execution only when every confirmed member is eligible, without changing queue recency or selecting newer jobs; otherwise it must create no recovery execution.
+- R5. Exact recovery must assert the requested source membership, evaluate and report each member's eligibility without partial creation, create no substitutes, reuse valid run identity, and require a fresh browser binding and inspection epoch. The KTD3 addendum below supersedes the original partial-eligibility model: any ineligible confirmed member rejects the whole set and creates no recovery execution.
+- R6. Exact recovery must reject foreign-user, revoked, changed-requisition, duplicate, and concurrently owned members. Already-applied members are reconciliation-only, not recovery-eligible; including one in the confirmed set must fail the request atomically. Reconcile that member through its review-handoff/outcome path, and recover any still-eligible sibling only through a separately confirmed exact set. An inactive member likewise makes the confirmed exact set ineligible. Authentication, account creation, OTP, CAPTCHA, and other runtime access barriers are not pre-creation eligibility facts; discover and persist them afterward as typed, non-counting live dispositions.
 - R7. Tab restoration, form restoration, and mutation authority must be exposed as separate value-free recovery facts.
 
 **Review and submission reconciliation**
@@ -84,8 +84,8 @@ None of these receipts implies another.
 - F1. Exact interrupted-member recovery
   - **Trigger:** A prior execution expired or ended after tabs or form state were lost.
   - **Actors:** User, Trackly backend, MCP client, browser harness.
-  - **Steps:** The client lists bounded backend-owned recoverable source summaries when local identity is absent; the user confirms the exact candidate set; the client requests those source candidates; the backend validates the immutable source set and returns eligibility; the backend creates one exact recovery execution; the harness verifies returned membership; the harness obtains fresh browser and mutation receipts; the harness rehydrates only blank or agent-owned controls.
-  - **Outcome:** Only the requested eligible jobs become mutable. Queue ordering is unchanged.
+  - **Steps:** The client lists bounded backend-owned recoverable source summaries when local identity is absent; the user confirms the exact candidate set; the client requests those source candidates; before creation, the backend validates the immutable source set and confirms that every requested candidate is eligible; only then does the backend create one exact recovery execution; the harness verifies returned membership; the harness obtains fresh browser and mutation receipts; the harness rehydrates only blank or agent-owned controls.
+  - **Outcome:** Either the full confirmed set becomes mutable or no recovery execution is created. Queue ordering is unchanged.
   - **Covered by:** R4-R7, R18, R22-R23.
 
 - F2. Cumulative two-job completion
@@ -132,15 +132,15 @@ None of these receipts implies another.
 
 - AE3. **Exact recovery with newer jobs present**
   - **Covers:** R4-R7.
-  - **Given:** Two expired source members and newer Check Later jobs exist.
+  - **Given:** Two eligible expired source members and newer Check Later jobs exist.
   - **When:** The user requests recovery of those two source members.
-  - **Then:** Only the eligible requested jobs enter the recovery execution and queue timestamps remain unchanged.
+  - **Then:** Both requested jobs, and no others, enter the recovery execution; queue timestamps remain unchanged.
 
 - AE4. **Mixed exact recovery set**
   - **Covers:** R5-R7, R13.
   - **Given:** One source member is applied, one is recoverable, and one is inactive.
   - **When:** Recovery is requested for all three.
-  - **Then:** Identity assertion covers all three, per-member results explain each disposition, and the recovery execution contains only the recoverable member with no replacement.
+  - **Then:** Identity assertion and per-member eligibility evaluation cover all three, the request fails atomically, and no recovery execution or replacement is created.
 
 - AE5. **Ashby same-route success**
   - **Covers:** R9-R12, R21.
@@ -209,7 +209,9 @@ None of these receipts implies another.
 
 - KTD1. **Persist completion credit in an append-only achievement ledger.** (session-settled: user-approved — chosen over concurrent unsubmitted inventory: once a job is ready or submitted it remains part of the requested total.) Create one value-free credit per `(execution_id, user_id, frozen_job_id)`, constrained to reviewed sources such as `review_ready` and `submitted_repair`. Insert the credit in the same transaction as the durable outcome. Expose `achievementCount` as the raw unique effective-credit count and compute target-facing `completed = LEAST(achievementCount, target)`. Credits are the sole target-achievement input; current ready/submitted counts remain operator projections. Do not add mutable columns to immutable execution candidates. A credit later proven to originate from invalid evidence may be neutralized only by an append-only compensating revocation through an audited internal repair operation; later submission or lifecycle change is never a revocation reason. Governs R1-R3.
 - KTD2. **Characterize the live state sequence before changing accounting.** Current unit tests already cover `ready + submitted`, so implementation begins with a Postgres-backed checkpoint, certification, bulk-outcome, submission, and progress-read reproduction. A passing unit calculator test is not sufficient evidence. Governs R1-R3, R8.
-- KTD3. **Model exact recovery as a new execution mode over stable source candidates.** Use `recover_exact_members` with `sourceExecutionId`, exact execution-candidate IDs proven inside the source snapshot hash, optimistic revision, and idempotency key. Persist `source_execution_id`, `source_candidate_id`, and the attempt-specific `source_member_id` when present. The identity assertion is atomic; eligibility may be partial, but the server creates no substitutes. Governs R4-R7.
+- KTD3. **Model exact recovery as a new execution mode over stable source candidates.** The original August 5 decision used `recover_exact_members` with `sourceExecutionId`, exact execution-candidate IDs proven inside the source snapshot hash, optimistic revision, and idempotency key. It persisted `source_execution_id`, `source_candidate_id`, and the attempt-specific `source_member_id` when present; identity assertion was atomic, eligibility could be partial (superseded—see the shipped-contract addendum immediately below), and the server created no substitutes. Governs R4-R7.
+
+  **Shipped-contract addendum (2026-08-13):** Backend implementation and adversarial review superseded partial eligibility with an atomic all-or-nothing eligibility check. If any confirmed candidate is no longer eligible, the server creates no recovery execution and no substitutes. AE4 and U4 below reflect this shipped contract while the original decision remains recorded here.
 - KTD4. **Restrict initial recovery to one source execution.** This keeps authorization, ordering, and historical semantics bounded. Arbitrary job IDs or cross-execution recovery remain deferred. Governs R4-R6.
 - KTD5. **Reuse the existing evidence and outcome repair path behind a typed local detection boundary.** Provider recognition produces a local `DetectedSubmission` containing provider strategy version, handoff/member identity, inspection epoch, bounded evidence type, confidence, and a value-free fingerprint. The fingerprint is a canonical digest only of provider strategy version, bounded evidence type, backend-owned handoff/member identity, and inspection epoch; DOM text, field values, URLs, paths, filenames, and raw browser identifiers are prohibited inputs. Group reconciliation yields one of `detected`, `user_confirmed`, `unresolved`, or `contradictory` per member. Only the existing typed evidence/outcome path writes backend state; page text stays local. Governs R10-R12, R21.
 - KTD6. **Create a first-class execution-owned review-handoff receipt.** Truth attestations remain batch-scoped certification evidence, but they cannot safely own a visible handoff spanning replacement waves. Persist an ordered set of `{batchId, memberId, runId, memberVersion, inspectionEpoch}`, its hash, and lifecycle `active | partially_reconciled | resolved | superseded | expired`. Creating a new receipt may supersede an older unresolved receipt only when the new ordered set contains every unresolved older member; otherwise both remain addressable and an unqualified group phrase is ambiguous. The first group-language reconciliation atomically claims the receipt under the outcome request idempotency key and stores the exact per-member result; retries return that result. Later confirmation must name the receipt and its unresolved members. A receipt becomes partially reconciled after a strict subset reaches durable submission, resolved after all members do, and expired only after its bounded handoff window. Group phrases resolve to an explicit receipt ID or to the sole unambiguous active/partially reconciled receipt. Governs R9-R10.
@@ -333,9 +335,9 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 - **Dependencies:** U2-U3.
 - **Repositories:** `close-ai`.
 - **Files:** `src/services/application-profile/apply-execution-contract.ts`, `src/services/application-profile/batch-service.ts`, `src/services/application-profile/service.ts`, `src/routes/trackly-apply.ts`, `src/mcp/server.ts`, execution service/route/MCP contract tests.
-- **Approach:** Add an authenticated discovery read returning only the user's recoverable execution IDs, snapshot hashes, stable candidate IDs, bounded lifecycle/eligibility codes, and expiry. It must not return profile values, browser data, or local paths. After explicit exact-set confirmation, create recovery with source execution, stable execution-candidate list, source snapshot hash, and idempotency key. Validate ownership and no competing mutable execution under the documented lock order. Return eligibility for the asserted source set, preserve source execution/candidate/member lineage, create one immutable non-replenishing recovery execution for eligible candidates, and require fresh epochs and browser bindings. Separate operational expiry from a bounded recovery-retention boundary so the nightly purge cannot erase eligible identity mid-window.
-- **Test scenarios:** Complete local context loss followed by discovery; cross-user discovery rejection; explicit exact-set confirmation; newer queue candidates present; saved timestamps unchanged; mixed eligible/applied/inactive set; duplicate IDs; changed requisition; foreign user; concurrent identical recovery; concurrent different recovery; old evidence rejected; second interruption; recovery immediately before and after operational expiry; recovery after daily purge but before `recoverable_until`; rejection after retention expiry.
-- **Verification:** AE3-AE4 pass and the response membership hash exactly matches the eligible subset of the asserted source set.
+- **Approach:** Add an authenticated discovery read returning only the user's recoverable execution IDs, snapshot hashes, stable candidate IDs, bounded lifecycle/eligibility codes, and expiry. It must not return profile values, browser data, or local paths. After explicit exact-set confirmation, create recovery with source execution, stable execution-candidate list, source snapshot hash, and idempotency key. Validate ownership and no competing mutable execution under the documented lock order. Evaluate eligibility for the entire asserted source set before creation; if any confirmed candidate is ineligible, fail atomically without creating an execution or substituting another candidate. When all are eligible, preserve source execution/candidate/member lineage, create one immutable non-replenishing recovery execution for the exact confirmed set, and require fresh epochs and browser bindings. Separate operational expiry from a bounded recovery-retention boundary so the nightly purge cannot erase eligible identity mid-window.
+- **Test scenarios:** Complete local context loss followed by discovery; cross-user discovery rejection; explicit exact-set confirmation; newer queue candidates present; saved timestamps unchanged; wholly eligible set; mixed eligible/applied/inactive set rejected with no execution; duplicate IDs; changed requisition; foreign user; concurrent identical recovery; concurrent different recovery; old evidence rejected; second interruption; recovery immediately before and after operational expiry; recovery after daily purge but before `recoverable_until`; rejection after retention expiry.
+- **Verification:** AE3-AE4 pass; AE4 explicitly proves that an ineligible confirmed member yields zero recovery executions, and every execution created by an eligible case has a response membership hash that exactly matches the full asserted source set.
 
 ### U5. Publish protocol and MCP recovery parity
 

package/docs/solutions/integration-issues/durable-exact-recovery-after-browser-state-loss.md

@@ -0,0 +1,126 @@
+---
+title: Durable exact recovery after browser state loss
+date: 2026-08-13
+category: integration-issues
+module: Trackly Apply durable recovery
+problem_type: integration_issue
+component: assistant
+symptoms:
+  - Restored browser tabs had lost unsaved application-form values after a browser or laptop restart
+  - A Zoox submission attempt reached ERR_FILE_NOT_FOUND without evidence identifying the failed upload stage or cause
+  - Earlier browser observations could appear valid even though they belonged to an obsolete inspection epoch
+  - Authentication and pre-form challenge pages risked being mistaken for completed accessible applications
+root_cause: missing_workflow_step
+resolution_type: code_fix
+severity: high
+related_components: [service_object, tooling, development_workflow]
+tags: [trackly-apply, exact-recovery, browser-restart, inspection-epoch, manual-submit, durable-handoff]
+---
+
+# Durable exact recovery after browser state loss
+
+## Problem
+
+Trackly Apply previously had no complete recovery contract for the gap between durable execution state and ephemeral browser state. A laptop restart, browser relaunch, renderer crash, lost automation connection, or missing local upload artifact could leave a server execution intact while destroying the tab handle, DOM snapshot, unsaved employer-form values, field provenance, or upload handle that had authorized the next mutation.
+
+The shipped recovery contract separates those layers. Exact recovery restores only a user-confirmed, server-retained candidate lineage; the agent must independently restore the browser surface, revalidate or reconstruct the form, and reacquire current mutation authority before writing anything.
+
+## Symptoms
+
+- Session evidence from the August 4–5 Apply run: after Chrome relaunched, previously filled Ontic and Lila forms appeared empty even though their tabs had been restored. The tab list survived, but the unsaved application DOM did not.
+- Session evidence from the same run: a Zoox submission attempt navigated to Chrome's `ERR_FILE_NOT_FOUND`. The failed upload stage and underlying cause were not captured, so the cause remains unknown.
+- A tab could remain visible to the user while disappearing from the automation controller, or the controller could retain a stale handle after navigation or a renderer restart. Application identity must not be inferred from window position, a transient tab number, or title text alone (`skills/trackly-apply/references/browser-lifecycle.md`, opening identity rules).
+- Earlier field checks, upload evidence, and review receipts could look plausible after recovery while belonging to an obsolete inspection epoch (`skills/trackly-apply/references/batch-orchestration.md`, “Exact recovery after local context loss”).
+- Authentication, account creation, OTP, and pre-form CAPTCHA pages could be mistakenly counted toward the review-ready target even though no safely accessible form existed. These classifications consume no completed slot (`skills/trackly-apply/references/batch-orchestration.md`, “Parent execution and child waves”).
+
+## What Didn't Work
+
+### Choosing external Chrome or the in-app browser as the persistence strategy
+
+Neither browser is a durable store. External Chrome can restore tabs without restoring page-local draft state; an in-app renderer or its automation connection can also restart or lose its controller inventory. Changing browser hosts may improve control availability, but it cannot make DOM state, tab handles, file chooser handles, or local upload paths authoritative.
+
+### Treating tab presence as proof of saved form state
+
+A restored URL proves only that a page can be reopened. It does not prove that the employer saved the draft, that the same requisition is loaded, that user edits survived, or that Trackly still authorizes mutation. Recovery therefore requires three separate proofs: tab restoration, form-state restoration or safe reconstruction, and current mutation authority (`skills/trackly-apply/references/browser-lifecycle.md`, “Missing-tab recovery”).
+
+### Reusing cached resume paths
+
+Regardless of the unclassified Zoox failure's cause, an earlier local path cannot be reused as attachment evidence. A prepared artifact may expire, move, or be deleted while the browser still displays an old reference. The supported sequence verifies the prepared resume immediately before attachment, checks the employer-facing committed filename, and rechecks parser-sensitive fields (`skills/trackly-apply/references/browser-upload.md`, “Capability gate”).
+
+### Using generic advancement or replacement after context loss
+
+Generic “continue with the next job” behavior is wrong for exact recovery because it can substitute newly saved or similar jobs for the user's original applications. Fixed membership may not be replaced, rescored, or expanded (`skills/trackly-apply/references/batch-orchestration.md`, “Freeze before browser work”). Recovery must use one retained source snapshot and exactly the candidates the user confirmed.
+
+### Refilling from profile data without provenance
+
+Blind autofill can overwrite a correction the user made after the agent's last observation. After ledger loss, every unexplained non-empty field becomes `unknown_external_change` and must be preserved; only safely empty or still agent-owned fields may be filled (`skills/trackly-apply/references/browser-lifecycle.md`, “Local tab ledger”).
+
+## Solution
+
+The coordinated durable recovery work shipped through [trackly-cli PR #100](https://github.com/trackly-app/trackly-cli/pull/100), which enforces exact-set discovery and response validation in the CLI/MCP/skill layer, and [close-ai PR #1391](https://github.com/trackly-app/close-ai/pull/1391), whose backend implementation owns atomic all-or-nothing recovery creation.
+
+### 1. Discover a bounded, value-free recovery menu
+
+Before discovery, call `trackly_get_apply_protocol` and require the advertised CLI, skill, MCP-contract, rollout, and browser capabilities to be compatible with exact recovery. If they are incompatible or exact recovery is disabled, stop without mutation; retained older work may use only the legacy recovery path explicitly published by that protocol (`skills/trackly-apply/SKILL.md`, “Preflight”). Then call `trackly_get_active_apply_execution`. When it returns `active: true`, reclaim that execution and its unresolved waves instead of listing or creating terminal exact recovery. Only when it proves there is no active execution may the compatible server's retained terminal lineage be listed with `trackly_list_recoverable_apply_executions`. The response exposes stable source execution IDs, snapshot hashes, candidate IDs, job IDs, queue positions, and eligibility codes; duplicate source and candidate identities are rejected (`mcp/apply-tools.js`, `recoverableCandidateSchema` and `recoverableExecutionsResponseSchema`). Resolve each job through Trackly and present the exact company, role, requisition identity when available, and source execution. Never reconstruct identity from chat, tab order, page copy, or search results (`skills/trackly-apply/references/batch-orchestration.md`, “Exact recovery after local context loss”).
+
+### 2. Require explicit confirmation of one exact set
+
+Call `trackly_recover_exact_apply_members` only with one discovered source execution, that source's snapshot hash, unique confirmed candidate IDs, `explicitExactSetConfirmation: true`, and a fresh idempotency key. Before the write, the CLI rejects an undiscovered source, changed snapshot hash, or candidate outside the latest discovery menu (`mcp/apply-tools.js`, `trackly_recover_exact_apply_members` registration).
+
+Recovery is all-or-nothing at the client boundary. The response validator requires `assertedCandidateIds`, `eligibleCandidateIds`, and every eligibility row to equal the requested set exactly, without duplicates or non-recoverable results (`mcp/apply-tools.js`, `validateExactRecoveryResponse`). This prevents partial recovery, substitution, and replenishment. Frozen order and membership remain server-owned.
+
+### 3. Restore browser state and authority independently
+
+Recovery creation does not grant a usable batch lease. First consume the recovery response's authoritative `progress` and obey `progress.nextAction`; stop or perform the specified non-browser action when the directive is blocking or terminal, and claim browser work only when that directive makes it actionable. Then consume every actionable entry in the recovered execution's `unresolvedWaves` in ascending `waveOrder`; `currentWave` is only the latest scheduling identity, never the complete recovery set. For each actionable unresolved wave, page only its exact linked batch with `trackly_get_apply_batch`, then acquire or renew ownership with `trackly_claim_apply_batch` using the latest revision. Use only the member/version/epoch/lease binding returned by that claim (`skills/trackly-apply/SKILL.md`, “Start every run”; `skills/trackly-apply/references/batch-orchestration.md`, “Backend tool sequence”).
+
+Branch on each claimed recovered member's run binding. If `runId` is absent, call `trackly_start_apply_run` with that exact current binding. Stop without browser binding or private-data mutation when the returned run has a non-null `executionBlocker`; otherwise call `trackly_bind_apply_surface` for the returned run with `initial_binding` and its current batch/member/version/epoch/lease plus browser-binding inputs. If `runId` already exists, first verify that run's published protocol remains compatible with the negotiated exact-recovery contract, then reuse it and, after the same non-null `executionBlocker` stop gate, call `trackly_bind_apply_surface` with `recovery_binding` for every recovered surface, including a still-visible, reopened, or reclaimed exact tab. Never start a replacement run merely because browser control was interrupted. The returned member version and inspection epoch are authoritative, and prior-epoch evidence is invalid (`skills/trackly-apply/SKILL.md`, “Start every run”; `skills/trackly-apply/references/browser-lifecycle.md`, “Reconciliation”). Execute the run's published origin policy, then revalidate HTTPS origin, employer, role, requisition, job identity, semantic controls, and ATS tenant only when that policy makes a separate tenant applicable; `trackly_employer_source_exact_origin` does not require one. Reinventory the entire form because a draft must never be assumed to have survived a crash or handoff (`skills/trackly-apply/references/browser-lifecycle.md`, “Missing-tab recovery”).
+
+The durable operator receipt must separately report whether the exact tab was restored, whether employer form state was restored or safely reconstructed, and whether current mutation authority was reacquired. It must also carry completed work, unresolved members, the user's exact next action, the exact resume phrase or observable event that unblocks it, the agent's next action, each browser surface, and the authoritative execution funnel. A missing original tab may be reopened from the exact backend URL; mutation requires the resulting form to be restored or safely reconstructed and current authority to be reacquired, while the tab-restoration fact remains independently reported.
+
+Before each claimed batch's first recovered form mutation, offer that exact batch's optional receipt-deduplication check once, keyed by its immutable batch ID and membership hash. Declining or lacking an approved inbox connector never blocks browser work. If the user opts in and a receipt matches, resolve its exact requisition and submission evidence through the documented confirmation and outcome path before mutating that affected member; never infer a duplicate from employer name alone or let the optional check expand the frozen set (`skills/trackly-apply/SKILL.md`, “Start every run”).
+
+Before any recovered form write, prove the adapter can preserve every target tab through either a usable session finalizer with a complete controller-owned plus user-owned inventory union, or a documented per-tab durable-handoff primitive with a verifiable persistence receipt. If neither preservation path works end to end, stop before private-data mutation. Then report a committed same-run `browser_ready` observation for every current run that will proceed, using its exact current batch, member, inspection epoch, browser surface, and browser-binding hash. Stop the affected run without private-data mutation if Trackly does not durably accept that readiness attestation; this gate applies whether or not the form has a Resume/CV control (`skills/trackly-apply/SKILL.md`, “Start every run”; `skills/trackly-apply/references/browser-lifecycle.md`, “Preserving browser state at turn end”).
+
+### 4. Park access barriers before form mutation
+
+Classify the entire current wave with the typed value-free set: `accessible`, `authentication_required`, `account_creation_required`, `otp_required`, `captcha_before_form`, `captcha_at_submit`, `manual_only`, or `unknown_unobservable` (`skills/trackly-apply/references/batch-orchestration.md`, “Parent execution and child waves”). Record every live result through `trackly_record_apply_execution_dispositions` with the exact current-wave job, batch, member, run, member-version, inspection-epoch, and browser-surface binding. Do not begin provenance inventory, resume preparation, attachment, or any other form mutation for an accessible sibling until the complete current probe set is durably accepted. Authentication, account creation, OTP, and pre-form CAPTCHA consume no target slot. A submit-time CAPTCHA can remain review-ready because the user owns the final action; the agent never solves, stores, or bypasses it (`skills/trackly-apply/references/batch-orchestration.md`, “Challenge placement”).
+
+### 5. Preserve user-owned and unknown values
+
+Take a fresh semantic inventory before the first write. Maintain provenance by execution, run, inspection epoch, and semantic field fingerprint. Preserve `user_edited` values byte-for-byte. If the ledger was lost, classify every unknown non-empty value as `unknown_external_change` instead of refilling (`skills/trackly-apply/references/browser-lifecycle.md`, “Local tab ledger”). Resume parsing, rerendering, recovery, and final validation cannot overwrite those values (`skills/trackly-apply/SKILL.md`, “Fill the form”).
+
+### 6. Reverify the exact resume at attachment time
+
+Before inspecting attachment controls, require the active browser adapter to advertise semantic control discovery; fail closed without inspecting or guessing when that capability is absent. Use it to discover whether the form has a real semantic Resume/CV attachment control. If it does not, skip the entire resume approval and upload sequence. For each current recovered run with a real Resume/CV control, call `trackly_prepare_resume` with that exact run ID, browser surface, and browser-binding hash, and let the user inspect the prepared file plus its exact resume ID, SHA-256, filename, size, and expiry. Reuse execution-scoped resume approval only when Trackly then proves the same prepared resume hash, profile revision, snapshot lineage, and an unexpired approval; otherwise obtain fresh approval for that verified prepared artifact and recovered execution. Bind confirmation to the current run and SHA-256. Then require chooser arming, file attachment, committed-filename inspection, and parser-field recheck. If approval, run-bound preparation and confirmation, or any capability is missing, fail closed and hand the upload to the user before opening a chooser. Arm and prove the discovered control's chooser, run `trackly_verify_prepared_resume` with the current prepare-issued proof, and immediately attach only that verified artifact. Verify the visible employer-facing filename and recheck every field the parser may have changed. Pass the six ordered value-free stage outcomes to `trackly_validate_apply_resume_upload`; stop or hand off unless it returns `safeToClaimAttachment: true` (`skills/trackly-apply/references/browser-upload.md`, “Capability gate”). An earlier approval proves which content the user authorized; it does not prove which bytes the current employer form received.
+
+### 7. Stop at manual review
+
+Submit remains a hard human boundary. The skill forbids the agent from clicking Submit even when the user previously approved submission (`skills/trackly-apply/SKILL.md`, “Non-negotiable rules”). When a recovered form passes every review gate, checkpoint it with `review/manual_submit` and its exact current epoch, then obtain final truth certification for the exact complete ready subset with the correct `resumeDependency` branch: use `approved` plus the exact approved resume identity when any certified member depends on an attachment, or `not_applicable` with no resume ID/hash when no certified member has a Resume/CV control. Record literal `outcome: review_ready`, and verify every returned run is `awaiting_manual_submit` before presenting the handoff. Focus or reveal each exact review tab and prove current adapter-visible presentation or a current tab-bound handoff receipt; inventory membership alone is not visibility proof. If presentation cannot be proven, use the visibility-unverified handoff and do not instruct the user to Submit (`skills/trackly-apply/SKILL.md`, “Review handoff”; `skills/trackly-apply/references/browser-lifecycle.md`, “Visible review tabs”). After any grouped human submission statement, first call `trackly_list_apply_review_handoffs` and resolve the statement to the named receipt or sole active receipt; if more than one receipt could match, ask instead of guessing. For a fresh receipt, classify every member in its exact set and call `trackly_claim_apply_review_handoff` once. For a `partially_reconciled` receipt, preserve its immutable stored claim and classifications, skip every member already reconciled, and never issue a fresh claim for that receipt. In either branch, write submission evidence and outcomes only for unreconciled members classified `detected` or `user_confirmed`; ask the user once about `unresolved` members, and preserve `contradictory` members without a success write. Refetch every affected member and require both member lifecycle `submitted` and job state `applied_confirmed`; on conflict, preserve the tab, refresh once, and replay only the documented idempotent evidence/outcome sequence. If either durable state remains unproven, report the reconciliation defect and leave the tab open without claiming completion (`skills/trackly-apply/SKILL.md`, “Review handoff”; `skills/trackly-apply/references/review-handoff.md`, “Group submission reconciliation”).
+
+At browser-turn end, execute—not merely advertise—the preservation path proven before mutation. For the session-finalizer path, immediately before finalization call `trackly_validate_apply_tab_keep_set` with the expected set, keep set, and complete controller-owned plus user-owned inventories; continue only when it returns `safeToFinalize: true`, then call the one finalizer with that validated keep set. Otherwise perform and verify the documented durable handoff for every live application tab. Require the finalizer result or every per-tab persistence receipt before reporting the recovered review handoff complete (`skills/trackly-apply/SKILL.md`, “Non-negotiable rules”; `skills/trackly-apply/references/browser-lifecycle.md`, “Preserving browser state at turn end”).
+
+## Why This Works
+
+The solution places authority in records that survive a browser crash: the server-retained source execution, immutable snapshot hash, exact candidate identities, member versions, inspection epochs, and idempotent mutation receipts. Browser state remains evidence, never authority by itself.
+
+Set equality closes substitution. Discovery establishes the eligible menu, explicit confirmation binds user intent to it, the pre-write cache rejects undiscovered candidates, and post-write validation requires every candidate collection to equal the request. A partially eligible response cannot be rationalized into a “close enough” recovery.
+
+Inspection epochs close stale-evidence reuse. Field provenance protects user corrections. Point-of-use resume verification distinguishes authorized content from the file actually committed to the employer form. Parking access barriers and preserving manual Submit prevent recovery pressure from weakening authentication, anti-bot, or consent boundaries.
+
+## Prevention
+
+- Model browser tabs, DOM snapshots, control handles, chooser handles, and local artifact paths as leases or observations, never durable state.
+- Bind every exact-recovery member's sanctioned surface: use `initial_binding` only for a newly started run, and use `recovery_binding` whenever recovery reuses an existing run—even when its exact tab is still visible. After ordinary navigation or rerender outside recovery, retain the current binding and revalidate identity, form state, and the semantic DOM before mutation.
+- Keep tab restored, form restored/reconstructed, and mutation authority reacquired as separate assertions in code, tests, and operator output.
+- Preserve exact recovery as a dedicated operation; never route it through normal advancement, refill, replacement, or “next candidate” logic.
+- Assert set equality and uniqueness on both sides of the mutation. Cover duplicate discovery identities, undiscovered candidates, changed snapshot hashes, partial eligible sets, substitutions, and non-recoverable rows.
+- Treat every unexplained non-empty field as protected after provenance loss.
+- Verify resume identity immediately before attachment, verify the committed filename immediately afterward, and re-snapshot parser-sensitive fields.
+- Keep authentication, account creation, OTP, and pre-form CAPTCHA parked and value-free; never count or auto-resume them.
+- Keep “Never Submit” in behavioral tests and handoff templates.
+
+## Related Issues
+
+- [Trackly CLI PR #100](https://github.com/trackly-app/trackly-cli/pull/100) — CLI, MCP, and skill-side durable exact recovery contract.
+- [Close AI PR #1391](https://github.com/trackly-app/close-ai/pull/1391) — backend durable recovery lineage and exact-member control plane.
+- [Durable recovery implementation plan](../../plans/2026-08-05-001-trackly-apply-durable-recovery-reconciliation-plan.md) — historical design record aligned with the released all-or-nothing recovery contract.

package/docs/trackly-tools.md

@@ -72,6 +72,7 @@ API-key creation attempts.
 
 ### Available Tools
 
+- **get_more_tools** — Report what the agent wanted to do when no Trackly tool fit, so Trackly can improve its MCP surface. The tool is always available; report delivery is best-effort and occurs only when usage analytics are enabled.
 - **trackly_search_jobs** — Search/filter jobs.
   - `function` (14 values): `product`, `engineering`, `design`, `data`, `marketing`, `sales`, `partnerships`, `finance`, `strategy`, `operations`, `people`, `legal`, `support`, `other`
   - `locationFilter`: pass ONE of

package/lib/client.js

@@ -10,6 +10,7 @@ const { version: PACKAGE_VERSION } = require('../package.json');
 const DEFAULT_CONFIG_DIR = path.join(os.homedir(), '.trackly');
 const DEFAULT_BASE_URL = 'https://closeai.mba';
 const DEFAULT_HTTP_TIMEOUT_MS = 30000;
+const ANALYTICS_PREFERENCE_SYNC_TIMEOUT_MS = 1500;
 const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
 const MAINTENANCE_CODE = 'maintenance_mode';
 const LEGACY_MAINTENANCE_CODE = 'planned_maintenance';
@@ -106,10 +107,180 @@ function saveConfig(config) {
 }
 
 function clearConfig() {
+  let config = {};
+  try {
+    const loaded = loadConfig();
+    if (loaded && typeof loaded === 'object' && !Array.isArray(loaded)) config = loaded;
+  } catch {
+    // Logout must still remove an invalid or unreadable credential file. The
+    // opt-out can be preserved only when the existing config is recoverable.
+  }
+  // A logout clears credentials and endpoint overrides, but the content-free
+  // analytics opt-out must continue suppressing anonymous MCP lifecycle events.
+  if (config.mcpAnalyticsOptOut === true) {
+    try {
+      saveConfig({ mcpAnalyticsOptOut: true });
+      return;
+    } catch {
+      // Preserving the marker is best-effort. A disk/write failure must never
+      // leave credentials behind, so fall through to unlinking the old file.
+    }
+  }
   const { file } = getConfigPaths();
   try { fs.unlinkSync(file); } catch (e) {}
 }
 
+function isRecord(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function hasAuthenticationInConfig(config) {
+  return Boolean(
+    (process.env.TRACKLY_API_KEY || '').trim()
+    || (isRecord(config) && (config.apiKey || config.token || config.refreshToken))
+  );
+}
+
+function configAfterCredentialRemoval(config, scope) {
+  const next = isRecord(config) ? { ...config } : {};
+  if (scope === 'all' || scope === 'apiKey') delete next.apiKey;
+  if (scope === 'all' || scope === 'oauth') {
+    delete next.token;
+    delete next.refreshToken;
+  }
+  return next;
+}
+
+async function resolveAnalyticsOptOutBeforeCredentialLoss(
+  request = apiRequest,
+  timeoutMs = ANALYTICS_PREFERENCE_SYNC_TIMEOUT_MS
+) {
+  const controller = new AbortController();
+  let timeout;
+  try {
+    const preference = await Promise.race([
+      Promise.resolve().then(() => request(
+        'GET',
+        '/api/jobscout/analytics-preference',
+        null,
+        false,
+        true,
+        null,
+        null,
+        { signal: controller.signal, timeoutMs }
+      )),
+      new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+          controller.abort();
+          reject(new Error('analytics_preference_sync_timeout'));
+        }, timeoutMs);
+      }),
+    ]);
+    if (typeof preference?.shareUsageAnalytics !== 'boolean') {
+      throw new Error('analytics_preference_invalid');
+    }
+    return preference.shareUsageAnalytics === false;
+  } catch {
+    // Fail closed: if the authoritative preference cannot be read before the
+    // final credential disappears, suppress future anonymous MCP capture.
+    return true;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function synchronizeAnalyticsPreferenceBeforeLogout(
+  request = apiRequest,
+  options = {}
+) {
+  const timeoutMs = options.timeoutMs ?? ANALYTICS_PREFERENCE_SYNC_TIMEOUT_MS;
+  try {
+    if (!hasAuth()) return;
+  } catch {
+    // A corrupt or unreadable config must never prevent logout. clearConfig()
+    // owns the best-effort removal path and will run immediately afterward.
+    return;
+  }
+  const optedOut = await resolveAnalyticsOptOutBeforeCredentialLoss(request, timeoutMs);
+  let config = {};
+  try {
+    const loaded = loadConfig();
+    if (loaded && typeof loaded === 'object' && !Array.isArray(loaded)) config = loaded;
+  } catch {
+    // Environment-provided authentication can still make the preference
+    // request valid when the on-disk config is corrupt. Replace only the
+    // recoverable analytics marker and let clearConfig() remove credentials.
+  }
+  if (optedOut) config.mcpAnalyticsOptOut = true;
+  else delete config.mcpAnalyticsOptOut;
+  try {
+    saveConfig(config);
+  } catch {
+    // Analytics synchronization is best-effort and must never block logout.
+  }
+}
+
+async function removeCredentials({
+  scope = 'all',
+  request = apiRequest,
+  timeoutMs = ANALYTICS_PREFERENCE_SYNC_TIMEOUT_MS,
+  preferenceUnavailable = false,
+} = {}) {
+  let config = {};
+  try {
+    const loaded = loadConfig();
+    if (isRecord(loaded)) config = loaded;
+  } catch {
+    // Corrupt or unreadable config still belongs to the best-effort removal
+    // path below. There is no safe credential state to preserve from it.
+  }
+
+  let next = configAfterCredentialRemoval(config, scope);
+  const removesEphemeralCredential = scope === 'all'
+    && Boolean((process.env.TRACKLY_API_KEY || '').trim());
+  const removesFinalCredential = removesEphemeralCredential
+    || (hasAuthenticationInConfig(config) && !hasAuthenticationInConfig(next));
+
+  if (removesFinalCredential) {
+    const optedOut = preferenceUnavailable
+      ? true
+      : await resolveAnalyticsOptOutBeforeCredentialLoss(request, timeoutMs);
+    if (optedOut) next.mcpAnalyticsOptOut = true;
+    else delete next.mcpAnalyticsOptOut;
+  }
+
+  if (scope === 'all') {
+    // Preserve logout's historical behavior of clearing endpoint overrides and
+    // all future config keys, with only the anonymous opt-out allowed through.
+    if (next.mcpAnalyticsOptOut === true) {
+      try {
+        saveConfig({ mcpAnalyticsOptOut: true });
+        return;
+      } catch {
+        // Credential removal wins over marker preservation on write failure.
+      }
+    }
+    const { file } = getConfigPaths();
+    try { fs.unlinkSync(file); } catch (_) {}
+    return;
+  }
+
+  if (Object.keys(next).length === 0) {
+    const { file } = getConfigPaths();
+    try { fs.unlinkSync(file); } catch (_) {}
+    return;
+  }
+  try {
+    saveConfig(next);
+  } catch (error) {
+    // If the surgical rewrite cannot be persisted, do not leave known-invalid
+    // credentials in the old file. Best-effort unlink is the safer fallback.
+    const { file } = getConfigPaths();
+    try { fs.unlinkSync(file); } catch (_) {}
+    throw error;
+  }
+}
+
 // Surgical alternative to clearConfig() for the refresh-failure path. Deletes ONLY the
 // OAuth credentials (token + refreshToken) while preserving everything else on disk
 // (baseUrl, apiKey, timeout overrides, future keys). A refresh token being invalidated
@@ -488,10 +659,10 @@ async function _doRefresh() {
     // Treat as an invalidated session and purge ONLY the OAuth pair so we don't retry on
     // every subsequent 401. Without this, a backend that signals failure via JSON instead of
     // a 4xx status would leave the user stuck in a doomed-refresh loop forever.
-    // Use clearOAuthTokens() — NOT clearConfig() — so the user's baseUrl, apiKey, and any
-    // other persisted settings survive a token expiry. (Bug caught by Cursor Bugbot on
-    // PR #20 post-review: the earlier clearConfig() call silently wiped baseUrl too.)
-    try { clearOAuthTokens(); } catch (_) {}
+    // Use the centralized OAuth-only removal — NOT clearConfig() — so the user's
+    // baseUrl, apiKey, and other persisted settings survive a token expiry while
+    // final-credential loss still preserves the analytics preference safely.
+    try { await removeCredentials({ scope: 'oauth', preferenceUnavailable: true }); } catch (_) {}
   } catch (e) {
     if (isMaintenanceError(e)) {
       throw e;
@@ -503,7 +674,7 @@ async function _doRefresh() {
     // purge the token. Surgical OAuth-only clear preserves baseUrl + apiKey + timeout overrides.
     const status = e && typeof e.status === 'number' ? e.status : null;
     if (status === 400 || status === 401 || status === 403) {
-      try { clearOAuthTokens(); } catch (_) {}
+      try { await removeCredentials({ scope: 'oauth', preferenceUnavailable: true }); } catch (_) {}
     }
   }
   return null;
@@ -516,7 +687,8 @@ function apiRequest(
   skipAuth = false,
   _isRetry = false,
   userAgent = null,
-  additionalHeaders = null
+  additionalHeaders = null,
+  requestOptions = null
 ) {
   return new Promise((resolve, reject) => {
     let url;
@@ -552,7 +724,15 @@ function apiRequest(
       headers['Idempotency-Key'] = idempotencyEntry[1];
     }
     const authMethod = getAuthMethod();
-    const timeoutMs = getRequestTimeoutMs();
+    const requestedTimeoutMs = Number(requestOptions?.timeoutMs);
+    const timeoutMs = Number.isFinite(requestedTimeoutMs) && requestedTimeoutMs > 0
+      ? Math.min(getRequestTimeoutMs(), requestedTimeoutMs)
+      : getRequestTimeoutMs();
+    const signal = requestOptions?.signal;
+    if (signal?.aborted) {
+      reject(new Error('Trackly request aborted.'));
+      return;
+    }
     const hasSensitivePayload = Boolean(data && typeof data === 'object' && 'refreshToken' in data);
 
     try {
@@ -640,7 +820,8 @@ function apiRequest(
                 false,
                 true,
                 userAgent,
-                additionalHeaders
+                additionalHeaders,
+                requestOptions
               );
               return resolve(retried);
             } catch (e) { return reject(e); }
@@ -671,6 +852,9 @@ function apiRequest(
     req.on('timeout', () => {
       req.destroy(new Error(`Trackly request timed out after ${timeoutMs}ms`));
     });
+    const abortRequest = () => req.destroy(new Error('Trackly request aborted.'));
+    signal?.addEventListener('abort', abortRequest, { once: true });
+    req.on('close', () => signal?.removeEventListener('abort', abortRequest));
     req.on('error', reject);
     if (data) req.write(JSON.stringify(data));
     req.end();
@@ -827,7 +1011,9 @@ module.exports = {
   normalizeMaintenance,
   normalizeEndpoint,
   refreshAccessToken,
+  removeCredentials,
   saveConfig,
+  synchronizeAnalyticsPreferenceBeforeLogout,
   CONFIG_DIR: DEFAULT_CONFIG_DIR,
   CONFIG_FILE: path.join(DEFAULT_CONFIG_DIR, 'config.json'),
 };