trackly-cli 0.22.3 → 0.23.0

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

@@ -47,5 +47,8 @@
   },
   "3.9.2": {
     "contractSha256": "d3a82489330d0b0062a1baec8d226b510628accc434731136dca9951ec64c302"
+  },
+  "3.9.3": {
+    "contractSha256": "0773b7fef8ac012fe028c7e61ecf00272122949290fe35f01aa577f63a4f01df"
   }
 }

package/contracts/trackly-apply-tools.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "3.9.2",
+  "contractVersion": "3.9.3",
   "constants": {
     "applyExecutionProtocolVersion": "trackly-apply-execution/v3",
     "applyAccessKnowledgeOrderingVersion": 3,
@@ -73,7 +73,7 @@
     "trackly_get_application_profile": "{includeSensitive:z.boolean().optional(),provider:z.string().max(100).optional(),companyId:z.string().max(100).optional(),jurisdiction:iso3166Alpha2Schema.optional(),office:officeScopeSchema.optional()}",
     "trackly_get_profile_onboarding": "{}",
     "trackly_update_application_profile": "{expectedRevision:z.number().int().min(1),source:z.enum(['web','ios','macos','codex','claude','mcp']).optional(),changes:z.array(z.discriminatedUnion('scope',[z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('global'),questionLabel:z.string().max(1000).optional()}),z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('provider'),scopeValue:z.string().min(1).max(200),questionLabel:z.string().max(1000).optional()}),z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('company'),scopeValue:z.string().min(1).max(200),questionLabel:z.string().max(1000).optional()}),z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('jurisdiction'),scopeValue:iso3166Alpha2Schema,questionLabel:z.string().max(1000).optional()}),z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('office'),scopeValue:officeScopeSchema,questionLabel:z.string().max(1000).optional()})])).max(100).optional(),education:z.array(z.object({school:z.string().min(1).max(500),degree:z.string().max(500).nullable().optional(),fieldOfStudy:z.string().max(500).nullable().optional(),gpa:z.string().max(50).nullable().optional(),startDate:z.string().max(50).nullable().optional(),endDate:z.string().max(50).nullable().optional()})).max(20).optional(),confirmProfile:z.boolean().optional(),sensitiveStorageConsent:z.boolean().optional(),sensitiveRevocationConfirmToken:z.string().regex(/^[a-f0-9]{64}$/).optional()}",
-    "trackly_start_apply_execution": "{mode:z.literal('complete_next_n_accessible'),target:z.number().int().min(1).max(APPLY_EXECUTION_MAX_TARGET),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_start_apply_execution": "{mode:z.literal('complete_next_n_accessible'),target:z.number().int().min(1).max(APPLY_EXECUTION_MAX_TARGET),jobIds:z.array(z.number().int().min(1)).min(1).max(APPLY_EXECUTION_MAX_TARGET).refine((ids)=>newSet(ids).size===ids.length,{message:'jobIdsmustbeunique'}).optional(),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
     "trackly_get_active_apply_execution": "{}",
     "trackly_get_apply_execution": "{executionId:z.number().int().min(1)}",
     "trackly_list_recoverable_apply_executions": "{}",

package/docs/trackly-tools.md

@@ -124,7 +124,7 @@ Actual failures retain `isError: true`, HTTP status when available, a closed `ca
 - **trackly_get_application_profile** — Get the versioned, scoped application profile.
 - **trackly_get_profile_onboarding** — Get backend-owned questions plus only missing/unconfirmed answers.
 - **trackly_update_application_profile** — Save explicit answer states with optimistic concurrency and global/provider/company scope. Setting `sensitiveStorageConsent=false` is destructive and requires a second call echoing the `sensitiveRevocationConfirmToken` from the returned challenge.
-- **trackly_start_apply_execution** — Start a server-owned `complete_next_n_accessible` execution with a target from 1–20, then consume the returned authoritative `progress` and `nextAction` before doing browser work.
+- **trackly_start_apply_execution** — Start a server-owned `complete_next_n_accessible` execution with a target from 1–20. For explicitly selected jobs, pass their exact ordered `jobIds` and set `target` to the list length; no unrelated replacements are allowed. Omit `jobIds` only for a requested recent-first queue target. Consume authoritative `progress` and `nextAction` before browser work; never retry a rejected exact selection as count-only.
 - **trackly_get_active_apply_execution** — Recover the active execution before legacy batch recovery.
 - **trackly_get_apply_execution** — Read an execution's latest current-wave identity and authoritative aggregate progress funnel.
 - **trackly_list_recoverable_apply_executions** — List a bounded, value-free menu of exact recovery candidates after local context loss.

package/lib/agent.js

@@ -8,7 +8,7 @@ const { spawnSync } = require('node:child_process');
 const { apiRequest, downloadFile, getConfigPaths, hasAuth, maintenanceOutput } = require('./client');
 const { version: PACKAGE_VERSION } = require('../package.json');
 const { contractVersion: MCP_CONTRACT_VERSION } = require('../contracts/trackly-apply-tools.json');
-const SKILL_VERSION = '4.9.2';
+const SKILL_VERSION = '4.9.3';
 const SKILL_POLICY_REVISION = SKILL_VERSION;
 const CLI_USER_AGENT = `trackly-cli/${PACKAGE_VERSION}`;
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;

package/mcp/apply-tools.js

@@ -976,13 +976,18 @@ function registerApplyTools(
 
   server.tool(
     'trackly_start_apply_execution',
-    'Start a server-owned execution that keeps selecting from one recent-first Check Later snapshot until the requested number of accessible forms is durably ready for manual review. Consume the returned authoritative progress and nextAction immediately; never infer the first wave or next step locally.',
+    'Start a server-owned no-submit execution. For named or explicitly selected jobs, supply their exact ordered jobIds and set target to their count; no replacement outside that set is allowed. Omit jobIds only for a user-requested recent-first queue target. Consume authoritative progress and nextAction; never fall back to count-only after an exact selection is rejected.',
     {
       mode: z.literal('complete_next_n_accessible'),
       target: z.number().int().min(1).max(APPLY_EXECUTION_MAX_TARGET),
+      jobIds: z.array(z.number().int().min(1)).min(1).max(APPLY_EXECUTION_MAX_TARGET)
+        .refine((ids) => new Set(ids).size === ids.length, { message: 'jobIds must be unique' }).optional(),
       idempotencyKey: z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY),
     },
     wrapTool(async ({ idempotencyKey, ...body }) => {
+      if (body.jobIds !== undefined && body.target !== body.jobIds.length) {
+        throw new Error('target must equal the jobIds selection length.');
+      }
       const rawResponse = await applyControlRequest(
         'POST', '/api/jobscout/apply/executions', body, idempotencyKey,
       );

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "trackly-cli",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "trackly-cli",
-      "version": "0.22.3",
+      "version": "0.23.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.32.1",
@@ -95,9 +95,9 @@
       }
     },
     "node_modules/@hono/node-server": {
-      "version": "2.0.12",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.0.12.tgz",
-      "integrity": "sha512-eWpQYr67tqJLeaSUl0Q+TquuYfUdTibpOJlUMV2FfUP7+KqCC5TufnwnlXL6mobZBJbGAYRd7ZvEBDCbLInjhg==",
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.3.tgz",
+      "integrity": "sha512-TA//nWMqPhbfdfneACk6t5a9eqbS9lABEPyKn0/xZTah3H3U2XaVg85rJFl0/Fyit0I552YDHgXGVSf3GwqbUw==",
       "license": "MIT",
       "engines": {
         "node": ">=20"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "mcpName": "io.github.trackly-app/trackly",
   "description": "Search Thousands of jobs across Thousands of companies with the Trackly CLI and MCP server for Claude, ChatGPT, Codex and Cursor. Filter by role, location, salary and sponsorship; track jobs and prepare applications.",
   "bin": {
@@ -82,7 +82,7 @@
     "node": "^20.20.0 || >=22.22.0"
   },
   "overrides": {
-    "@hono/node-server": "2.0.12",
+    "@hono/node-server": "2.1.3",
     "fast-uri": "3.1.9",
     "ip-address": "10.7.4",
     "qs": "6.16.1",

package/server.json

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

package/skills/trackly-apply/SKILL.md

@@ -11,7 +11,7 @@ Before application work, read [onboarding guidance](references/onboarding.md). G
 
 ## Skill version
 
-Skill version: `4.9.2`. Before browser readiness read [references/handoff-compatibility.md](references/handoff-compatibility.md). This policy takes precedence over returned-persistence-receipt or finalizer requirements elsewhere when using the documented markHandoff path. Other review and safety gates remain unchanged.
+Skill version: `4.9.3`. Before browser readiness read [references/handoff-compatibility.md](references/handoff-compatibility.md). This policy takes precedence over returned-persistence-receipt or finalizer requirements elsewhere when using the documented markHandoff path. Other review and safety gates remain unchanged.
 
 ## Non-negotiable rules
 
@@ -41,7 +41,7 @@ value-free phase receipt with `scripts/validate-phase-checkpoint.js` before
 claiming that phase complete.
 Read [references/legal-clarifications.md](references/legal-clarifications.md) when a form asks for a legal, regulatory, consent, or employer-relationship decision.
 
-1. Call `trackly_get_apply_protocol`. Skill 4.9.2 requires protocol 3.7.0 or newer for new reliability work. Protocol 3.2 remains valid only for an already-active explicit legacy single run; an already-active explicit 3.2 single run may finish through its legacy path. Preserve the protocol's documented recovery paths for already-active older work. Require `compatibleSkillMajor: 4` and `compatibleSkillMinimumVersion` no newer than this installed skill. Reject an older or incompatible version for new work 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.
+1. Call `trackly_get_apply_protocol`. Skill 4.9.3 requires protocol 3.7.0 or newer for new reliability work. Protocol 3.2 remains valid only for an already-active explicit legacy single run; an already-active explicit 3.2 single run may finish through its legacy path. Preserve the protocol's documented recovery paths for already-active older work. Require `compatibleSkillMajor: 4` and `compatibleSkillMinimumVersion` no newer than this installed skill. Reject an older or incompatible version for new work 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. When present, render `schema.screens` in ascending `order` as one grouped question packet per screen. Within a screen, preserve category `order` and then field `order`; use each field's user-facing `rationale` when the user asks why it is needed. Ask only unknown or confirmation-needed fields and honor `consistencyRules` before submitting profile changes, resolving contradictions with the user instead of guessing. When `schema.screens` is absent on a legacy backend, fall back to the existing category-based onboarding behavior. 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.
@@ -59,6 +59,7 @@ Read [references/legal-clarifications.md](references/legal-clarifications.md) wh
    - Infer a direct prior-employer answer of No only when the profile explicitly marks history complete, the target and backend-confirmed aliases are absent, and the question is limited to direct employment. Ask for subsidiary, affiliate, acquisition, contractor, or otherwise ambiguous relationships.
 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. For every protocol 3.4 or newer request, call `trackly_get_active_apply_execution` before legacy recovery. Resume execution work only when the response says `active: true`. A response with `preserved: true` and `active: false` exposes a stopped, closed, or otherwise terminal execution only for read-only reconciliation. Never fetch its compact snapshot, continue its wave, mutate its members, or interpret historical `currentlyFilling` or reservation counts as current work; require `progress.nextAction: none`. Only with protocol 3.5 or newer and an enabled compact-snapshot capability may an active recovery or new execution call `trackly_get_apply_execution_snapshot`, using only the current member IDs, profile keys needed by the visible forms, and actual browser surface. An already-active protocol 3.4 execution is read-only legacy recovery: use only its published get or stop operations, never call the 3.5-only snapshot, resume, approval, advance, or disposition tools, and never mutate its browser forms. For protocol 3.5 or newer, treat snapshot `mutable` and `allowedOperations` values as authoritative. Never mutate or reopen authentication, account-creation, OTP, pre-form-CAPTCHA, or manual-only members. Only an explicit user request may call `trackly_resume_parked_apply_member`; the returned member still requires a fresh non-mutating probe before private data or form mutation. Resume unresolved waves in ascending order only for `active: true` and obey the server `nextAction` and funnel. Never reconstruct progress or choose replacements locally. Treat backend `achievementCount`, target-capped `completed`, `targetReached`, and `nextAction` as authoritative. `durablyReviewReady` and `submitted` remain current operator projections and must never be added together by the client to reconstruct cumulative completion. Let the backend own reservations, capacity, attempted-job deduplication, immutable waves, and advancement. Continue until `targetReached`, `queueExhausted`, a blocking `nextAction`, or the user stops.
+   - For named jobs or an explicit selected set, resolve the exact Trackly job IDs and send their ordered `jobIds` to `trackly_start_apply_execution`, with `target` equal to that list length. The server must freeze only that set; blocked or inaccessible members never authorize unrelated replacements. Retain the original start idempotency key for an exact replay. A matching count alone never proves an active execution matches the selection. If the server cannot verify the exact selection, stop and explain the scope conflict; never omit `jobIds`, reorder the saved queue, or use count-only start as a fallback. Changing an active target still requires the existing explicit stop/change confirmation.
    - After full local context loss with no active execution, call `trackly_list_recoverable_apply_executions`. For every distinct returned `jobId`, call `trackly_get_job`, bind that Trackly-owned job record to the returned `candidateId`, and show the user its company, role, requisition identity when available, source-execution identity, and `accessKnowledge` scheduling reason when present; do not identify candidates from chat, tab order, search results, or page copy. A missing or mismatched Trackly job record blocks confirmation. An active personal deferment on any confirmed candidate blocks recovery until that deferment is cleared. Require explicit confirmation of one exact candidate set, then call `trackly_recover_exact_apply_members` with that source execution, snapshot hash, and only those candidate IDs. Verify `assertedCandidateIds`, `eligibleCandidateIds`, and the eligibility candidate IDs each contain exactly the confirmed set with no duplicates. Never add substitutes, newly saved jobs, or merely similar roles. Curated or historical walls stay in the exact recovered set as parked members and still require explicit resume plus a fresh probe.
    - Exact recovery restores server lineage only. Treat tab restored, form state restored, and mutation authority restored as three independent receipts. Bind every recovered surface with a fresh recovery binding and inspection epoch, revalidate the full form, and preserve every user-edited or unknown non-empty value before any write. Earlier-epoch browser, field, upload, integrity, and submission evidence cannot authorize the recovered form.
    - Every compact snapshot request must contain a non-empty list of only the current member IDs. Never request an empty or inferred all-members projection.
@@ -87,7 +88,7 @@ Read [references/legal-clarifications.md](references/legal-clarifications.md) wh
    - 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. When the selected job or current fixed batch member has no `runId`, call `trackly_start_apply_run` with the complete `batchId`, `memberId`, `expectedMemberVersion`, `expectedInspectionEpoch`, and `leaseToken` returned by Trackly. This is the sanctioned idempotent lookup for a recovered member whose `runId` is absent; call it with the exact recovered binding and Trackly will reuse the bound active run. When the member already has a `runId`, do not call `trackly_start_apply_run` in this or any subsequent start step: reuse that exact run and bind or recover its browser surface through `trackly_bind_apply_surface` as required. Never create a replacement run because browser control was interrupted.
    - If a bound start returns a transport failure, a non-access HTTP 5xx response, or an error explicitly marked `retryable: true`, preserve the frozen member and browser state. Refetch the active batch, renew its lease, and retry the same complete binding once. Classify the retry response independently with these same rules: route canonical `maintenance_mode` or legacy `planned_maintenance` directly through **Resume after maintenance**; surface controlled-access/request errors marked `retryable: false` and every other HTTP 4xx response unchanged; only a second transport failure, non-access HTTP 5xx response, or explicitly retryable error becomes `backend_run_start_unavailable`. Route maintenance on either attempt without consuming or relabeling the retry, and never relabel a permanent retry response as an outage. For `backend_run_start_unavailable`, continue other members and report a Trackly control-plane failure. Do not call `trackly_checkpoint_apply_batch` for this condition because start failure has not produced the required run ID. The unchanged frozen member is the durable resume point. Never switch that frozen member to an unbound legacy run or blame the employer form.
-   - Require `run.protocolVersion` to be 3.1.0 or newer and to share protocol major 3 with the fetched protocol. A new reliability execution member requires 3.7.0 or newer; already-active older work may use only the recovery path published by its fetched protocol. Never continue a pre-evidence 3.0.x run under skill 4.9.2. Preserve that run instead of starting a replacement, record it `blocked` with a value-free protocol-upgrade reason when possible, and tell the user the saved job can be retried only after the stale run is cleared through Trackly's supported lifecycle. Stop and refetch the protocol and active execution or batch if support level, execution mode, provider, required scenarios, authorized origin policy, member version, or inspection epoch changes after run creation.
+   - Require `run.protocolVersion` to be 3.1.0 or newer and to share protocol major 3 with the fetched protocol. A new reliability execution member requires 3.7.0 or newer; already-active older work may use only the recovery path published by its fetched protocol. Never continue a pre-evidence 3.0.x run under skill 4.9.3. 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 execution or 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.

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

@@ -24,6 +24,7 @@ runs remain recovery-only compatibility paths.
   active execution first or start one with target 1–20. Continue through its
   original recent-first Check Later snapshot until N forms are durably ready
   for manual review, the snapshot is exhausted, or the user stops it.
+- A request naming specific jobs means only those jobs. Resolve their Trackly IDs, pass the exact ordered `jobIds` with `target` equal to their count, and preserve that immutable selection through retries and later waves. Never fill unrelated jobs to replace blocked selected members. Keep the original idempotency key for an exact start replay; a changed key or set cannot authorize resuming a different active execution. A rejected selection must not fall back to a count-only start or queue reordering.
 - “Inspect the next N records” means a fixed immutable batch of exactly those
   queue records. Never replenish or replace that inspection batch.
 - A saved/check-later job is already approved. Neither mode rescans fit.