careervivid 2.1.36 → 2.1.39

package/dist/commands/apply.js

@@ -28,6 +28,7 @@ import { detectPlatform, getAdapter } from "../apply/index.js";
 import { loadProfile, saveProfile } from "../apply/gemini-agent.js";
 import { resolveResumePdf } from "../apply/resume-pdf.js";
 import { getOrGenerateAdapter, loadGeneratedAdapter } from "../apply/adapter-generator.js";
+import { verifyUrl } from "../agent/tools/urlVerifier.js";
 const { prompt } = pkg;
 // ── Config helpers ────────────────────────────────────────────────────────────
 function resolveModel(modelFlag) {
@@ -266,9 +267,27 @@ export function registerApplyCommand(program) {
             console.log(chalk.dim("  Example: cv jobs apply https://boards.greenhouse.io/stripe/jobs/7788088"));
             process.exit(1);
         }
-        // ── 3. Resolve resume PDF ────────────────────────────────────────────
+        // ── 3. Verify direct apply URL before any browser automation ──────────
+        console.log(chalk.dim("\n  Verifying apply link..."));
+        const verification = await verifyUrl(resolvedUrl);
+        if (!verification.ok) {
+            console.error(chalk.red(`\n❌ Apply link rejected: ${verification.reason}`));
+            if (verification.finalUrl && verification.finalUrl !== resolvedUrl) {
+                console.error(chalk.dim(`   Final URL: ${verification.finalUrl}`));
+            }
+            console.error(chalk.dim("   Search for a current direct apply page before running the harness.\n"));
+            process.exit(1);
+        }
+        if (verification.warning) {
+            console.log(chalk.yellow(`  ⚠️  ${verification.warning}`));
+        }
+        if (verification.finalUrl && verification.finalUrl !== resolvedUrl) {
+            console.log(chalk.dim(`  Redirect resolved: ${verification.finalUrl}`));
+            resolvedUrl = verification.finalUrl;
+        }
+        // ── 4. Resolve resume PDF ────────────────────────────────────────────
         const resumePdf = await resolveResumePdf();
-        // ── 4. Detect platform ───────────────────────────────────────────────
+        // ── 5. Detect platform ───────────────────────────────────────────────
         const platform = detectPlatform(resolvedUrl);
         const platformLabel = {
             greenhouse: "Greenhouse 🌱", lever: "Lever", ashby: "Ashby",
@@ -279,7 +298,7 @@ export function registerApplyCommand(program) {
         if (platform === "linkedin") {
             console.log(chalk.yellow("\n⚠️  LinkedIn requires manual apply — opening browser-use agent.\n"));
         }
-        // ── 5. Dry run ───────────────────────────────────────────────────────
+        // ── 6. Dry run ───────────────────────────────────────────────────────
         if (options.dryRun) {
             console.log(chalk.yellow("\n🔍 DRY RUN — nothing will open or be filled.\n"));
             const profileKeys = Object.keys(profile).filter((k) => profile[k]);
@@ -290,13 +309,13 @@ export function registerApplyCommand(program) {
             console.log(chalk.dim("  Re-run without --dry-run to execute.\n"));
             process.exit(0);
         }
-        // ── 6. Verification ──────────────────────────────────────────────────
+        // ── 7. Verification ──────────────────────────────────────────────────
         if (!llmConfig.apiKey && llmConfig.provider !== "careervivid") {
             console.log(chalk.red(`\n❌ No API key found for provider: ${llmConfig.provider}`));
             console.log(chalk.dim("   Set it via: cv agent config\n"));
             process.exit(1);
         }
-        // ── 7. HARNESS ROUTING ───────────────────────────────────────────────
+        // ── 8. HARNESS ROUTING ───────────────────────────────────────────────
         //
         //  Route A: Known platform → TypeScript adapter (fast, no LLM)
         //  Route B: Unknown platform → AI-generate new adapter

package/dist/commands/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqM1D"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAsM1D"}

package/dist/commands/auth.js

@@ -57,7 +57,7 @@ export function registerAuthCommand(program) {
         spinner?.stop();
         if (isApiError(result)) {
             if (jsonMode) {
-                console.log(JSON.stringify({ success: false, error: result.message }));
+                console.log(JSON.stringify({ success: false, ok: false, error: result.message }));
             }
             else {
                 console.error(`\n  ${chalk.red("✖")}  ${chalk.bold.red("Invalid key:")} ${result.message}`);
@@ -81,6 +81,7 @@ export function registerAuthCommand(program) {
         else {
             console.log(JSON.stringify({
                 success: true,
+                ok: true,
                 name: result.name,
                 email: result.email,
                 role: result.role,
@@ -110,7 +111,7 @@ export function registerAuthCommand(program) {
                     `\n  ${chalk.dim("Your key may have been revoked. Run")} ${chalk.cyan("cv login")} ${chalk.dim("to re-authenticate.\n")}`);
             }
             else {
-                console.log(JSON.stringify({ success: false, error: result.message }));
+                console.log(JSON.stringify({ success: false, ok: false, error: result.message }));
             }
             process.exit(1);
         }
@@ -127,7 +128,7 @@ export function registerAuthCommand(program) {
             }));
         }
         else {
-            console.log(JSON.stringify({ success: true, ...result }));
+            console.log(JSON.stringify({ success: true, ok: true, ...result }));
         }
     });
     // ── whoami ─────────────────────────────────────────────────────────────────
@@ -179,7 +180,7 @@ export function registerAuthCommand(program) {
         const { saveConfig } = await import("../config.js");
         saveConfig(config);
         if (jsonMode) {
-            console.log(JSON.stringify({ success: true }));
+            console.log(JSON.stringify({ success: true, ok: true }));
         }
         else {
             console.log();

package/dist/commands/interview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interview.d.ts","sourceRoot":"","sources":["../../src/commands/interview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAi1BpC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmG/D"}
+{"version":3,"file":"interview.d.ts","sourceRoot":"","sources":["../../src/commands/interview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAg6BpC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoG/D"}

package/dist/commands/interview.js

@@ -51,7 +51,7 @@ const CLI_BILL_URL = process.env.CV_FUNCTIONS_URL
 const CLI_CONTEXT_URL = process.env.CV_FUNCTIONS_URL
     ? `${process.env.CV_FUNCTIONS_URL}/cliGetInterviewContext`
     : "https://us-west1-jastalk-firebase.cloudfunctions.net/cliGetInterviewContext";
-const LIVE_MODEL = "gemini-3.1-flash-live-preview";
+const LIVE_MODEL = "gemini-live-2.5-flash-native-audio";
 const FEEDBACK_MODEL = "gemini-2.5-flash";
 const END_TOKEN = "<END_INTERVIEW>";
 const WRAP_WIDTH = 80;
@@ -252,9 +252,14 @@ async function callAgentProxy(opts) {
     const apiKey = getApiKey();
     if (!apiKey)
         throw new Error("No API key. Run: cv login");
+    // agentProxy backend only supports Gemini models (e.g., gemini-2.5-flash, gemini-3.5-flash)
+    // If a BYO model is passed that is not Gemini (e.g., openai/gpt-oss-120b:free), we fall back to FEEDBACK_MODEL.
+    const resolvedModel = opts.model && opts.model.toLowerCase().includes("gemini")
+        ? opts.model
+        : FEEDBACK_MODEL;
     const body = {
         apiKey,
-        model: FEEDBACK_MODEL,
+        model: resolvedModel,
         contents: opts.contents,
     };
     if (opts.systemInstruction)
@@ -306,7 +311,7 @@ ${questions.map((q, i) => `${i + 1}. ${q}`).join("\n")}
     return prompt;
 }
 // ─── Generate Questions (via agentProxy) ─────────────────────────────────────
-async function generateQuestions(role, numQuestions) {
+async function generateQuestions(role, numQuestions, model) {
     const spinner = ora(chalk.dim("Generating interview questions...")).start();
     try {
         const prompt = `Based on the following role, generate ${numQuestions} insightful interview questions covering technical skills, behavioral competencies, and role-specific scenarios. Return ONLY a valid JSON array of strings.\n\nRole: "${role}"`;
@@ -314,6 +319,7 @@ async function generateQuestions(role, numQuestions) {
             contents: [{ role: "user", parts: [{ text: prompt }] }],
             responseSchema: { type: "ARRAY", items: { type: "STRING" } },
             responseMimeType: "application/json",
+            model,
         });
         let clean = text.trim().replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
         const questions = JSON.parse(clean);
@@ -326,7 +332,7 @@ async function generateQuestions(role, numQuestions) {
     }
 }
 // ─── Analyze Transcript (via agentProxy) ─────────────────────────────────────
-async function analyzeTranscript(transcript, role) {
+async function analyzeTranscript(transcript, role, model) {
     const spinner = ora(chalk.dim("Generating feedback report...")).start();
     try {
         const formatted = transcript
@@ -347,6 +353,7 @@ async function analyzeTranscript(transcript, role) {
                 },
                 required: ["overallScore", "communicationScore", "confidenceScore", "relevanceScore", "strengths", "areasForImprovement"],
             },
+            model,
         });
         let clean = text.trim().replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
         const report = JSON.parse(clean);
@@ -360,7 +367,7 @@ async function analyzeTranscript(transcript, role) {
 }
 // ─── VOICE SESSION ────────────────────────────────────────────────────────────
 async function runVoiceSession(opts) {
-    const { role, questions, resumeContext, soxPath } = opts;
+    const { role, questions, resumeContext, soxPath, model } = opts;
     printBanner(role, "voice");
     // Create logger (sessionId not yet known — will be set after token vend)
     const log = createLogger("interview", {
@@ -410,6 +417,10 @@ async function runVoiceSession(opts) {
     // (outputBuf never contains END_TOKEN because chunkClean strips it, so the
     //  turnComplete check on outputBuf would never fire without this flag.)
     let endTokenSeen = false;
+    // Track audio bytes sent to speaker this turn to calculate mute duration
+    // 24kHz, 16-bit mono = 48000 bytes/second of playback
+    const SPEAKER_BYTES_PER_SEC = RECV_SAMPLE_RATE * 2; // 48000
+    let pendingAudioBytes = 0;
     // ── Audio processes ──────────────────────────────────────────────────
     const micProc = startMic(soxPath);
     const speakerProc = startSpeaker(soxPath);
@@ -454,6 +465,7 @@ async function runVoiceSession(opts) {
                             muteTimer = null;
                         }
                         const pcmBuf = Buffer.from(audioPart, "base64");
+                        pendingAudioBytes += pcmBuf.length;
                         speakerProc.stdin.write(pcmBuf);
                     }
                     // ── Output transcription (Vivid's words) — stream in real-time ──
@@ -535,15 +547,22 @@ async function runVoiceSession(opts) {
                             inputBuf = "";
                         }
                         if (!ended) {
+                            // Calculate exactly how long the buffered audio will take to play.
+                            // Show "Listening..." and unmute the mic together when playback ends.
+                            const playbackMs = Math.ceil((pendingAudioBytes / SPEAKER_BYTES_PER_SEC) * 1000);
+                            const muteMs = Math.max(playbackMs, 800); // minimum 800ms floor
+                            pendingAudioBytes = 0;
                             muteTimer = setTimeout(() => {
                                 vividSpeaking = false;
                                 muteTimer = null;
+                                // Show "Listening..." right as audio finishes playing
                                 if (!userSpeechLineActive) {
                                     process.stdout.write(chalk.green("\n  ● Listening...\r"));
                                 }
-                            }, 800);
+                            }, muteMs);
                         }
                         else {
+                            pendingAudioBytes = 0;
                             // Interview ended via END_TOKEN — cancel pending mute timer
                             // so '● Listening...' never appears after the interview concludes
                             if (muteTimer) {
@@ -554,10 +573,19 @@ async function runVoiceSession(opts) {
                     }
                 },
                 onerror: (e) => {
-                    console.log(chalk.red(`\n  Connection error: ${e.message ?? e}`));
+                    const msg = e?.message ?? JSON.stringify(e) ?? "Unknown error";
+                    console.log(chalk.red(`\n  ❌ Live API connection error: ${msg}`));
+                    console.log(chalk.dim(`     Model: ${LIVE_MODEL} | Location: ${location}`));
+                    ended = true;
+                },
+                onclose: (e) => {
+                    if (!ended) {
+                        const reason = e?.reason ?? e?.code ?? "unexpected close";
+                        console.log(chalk.yellow(`\n  ⚠️  Live API session closed unexpectedly: ${reason}`));
+                        console.log(chalk.dim(`     Model: ${LIVE_MODEL} | Location: ${location}`));
+                    }
                     ended = true;
                 },
-                onclose: () => { ended = true; },
             },
             config: {
                 responseModalities: [Modality.AUDIO],
@@ -641,7 +669,7 @@ async function runVoiceSession(opts) {
     console.log(chalk.dim("\n  Generating your personalized feedback report..."));
     let report = null;
     try {
-        report = await analyzeTranscript(transcript, role);
+        report = await analyzeTranscript(transcript, role, model);
         printReport(report);
         log.info("feedback_complete", { sessionId, overallScore: report.overallScore });
     }
@@ -680,42 +708,79 @@ async function runVoiceSession(opts) {
 }
 // ─── TEXT SESSION (fallback) ──────────────────────────────────────────────────
 async function runTextSession(opts) {
-    const { role, questions, resumeContext } = opts;
+    const { role, questions, resumeContext, model } = opts;
     const systemInstruction = buildSystemPrompt(role, questions, resumeContext);
     printBanner(role, "text");
     const history = [];
     const transcript = [];
     let ended = false;
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+    let sigintReceived = false;
+    let resolvePending = null;
+    const sigintHandler = () => {
+        if (sigintReceived)
+            return;
+        sigintReceived = true;
+        printSystem("Interview ended by user.");
+        rl.close();
+        if (resolvePending) {
+            resolvePending(null);
+        }
+    };
+    process.on("SIGINT", sigintHandler);
+    rl.on("SIGINT", sigintHandler);
     const askUser = () => new Promise(resolve => {
+        resolvePending = resolve;
         if (process.stdin.isTTY)
             process.stdout.write(chalk.white.bold("\n  you ❯ "));
-        rl.once("line", line => resolve(line.trim()));
-        rl.once("close", () => resolve(null));
+        rl.once("line", line => {
+            resolvePending = null;
+            resolve(line.trim());
+        });
+        rl.once("close", () => {
+            resolvePending = null;
+            resolve(null);
+        });
     });
+    const runAgentCall = async (contents) => {
+        return new Promise((resolve, reject) => {
+            resolvePending = (val) => resolve(null);
+            callAgentProxy({ contents, systemInstruction, model }).then(res => {
+                resolvePending = null;
+                resolve(res);
+            }, err => {
+                resolvePending = null;
+                reject(err);
+            });
+        });
+    };
     const spinner = ora(chalk.dim("Vivid is connecting...")).start();
     try {
-        const greeting = await callAgentProxy({
-            contents: [{ role: "user", parts: [{ text: "Hello" }] }],
-            systemInstruction,
-        });
+        const greeting = await runAgentCall([{ role: "user", parts: [{ text: "Hello" }] }]);
         spinner.stop();
-        history.push({ role: "user", parts: [{ text: "Hello" }] });
-        history.push({ role: "model", parts: [{ text: greeting }] });
-        transcript.push({ speaker: "user", text: "Hello" });
-        transcript.push({ speaker: "ai", text: greeting });
-        if (greeting.includes(END_TOKEN))
+        if (sigintReceived || greeting === null) {
             ended = true;
-        printAI(greeting);
+        }
+        else {
+            history.push({ role: "user", parts: [{ text: "Hello" }] });
+            history.push({ role: "model", parts: [{ text: greeting }] });
+            transcript.push({ speaker: "user", text: "Hello" });
+            transcript.push({ speaker: "ai", text: greeting });
+            if (greeting.includes(END_TOKEN))
+                ended = true;
+            printAI(greeting);
+        }
     }
     catch (err) {
         spinner.fail(chalk.red("Failed to connect to AI interviewer."));
         throw err;
     }
-    while (!ended) {
+    while (!ended && !sigintReceived) {
         const input = await askUser();
-        if (input === null || input.toLowerCase() === "exit" || input.toLowerCase() === "q") {
-            printSystem("Interview ended early.");
+        if (sigintReceived || input === null || input.toLowerCase() === "exit" || input.toLowerCase() === "q") {
+            if (!sigintReceived) {
+                printSystem("Interview ended early.");
+            }
             break;
         }
         if (input === "")
@@ -724,8 +789,11 @@ async function runTextSession(opts) {
         transcript.push({ speaker: "user", text: input });
         const aiSpinner = ora({ text: "" }).start();
         try {
-            const aiResponse = await callAgentProxy({ contents: history, systemInstruction });
+            const aiResponse = await runAgentCall(history);
             aiSpinner.stop();
+            if (sigintReceived || aiResponse === null) {
+                break;
+            }
             history.push({ role: "model", parts: [{ text: aiResponse }] });
             transcript.push({ speaker: "ai", text: aiResponse.replace(END_TOKEN, "").trim() });
             if (aiResponse.includes(END_TOKEN))
@@ -737,6 +805,7 @@ async function runTextSession(opts) {
             console.log(chalk.red(`\n  Error: ${err.message}\n`));
         }
     }
+    process.off("SIGINT", sigintHandler);
     rl.close();
     const userTurns = transcript.filter(t => t.speaker === "user").length;
     if (userTurns < 2) {
@@ -746,7 +815,7 @@ async function runTextSession(opts) {
     console.log(chalk.dim("\n  Generating your personalized feedback report..."));
     let textReport = null;
     try {
-        textReport = await analyzeTranscript(transcript, role);
+        textReport = await analyzeTranscript(transcript, role, model);
         printReport(textReport);
     }
     catch (err) {
@@ -781,6 +850,7 @@ export function registerInterviewCommand(program) {
         .option("-q, --questions <n>", "Number of interview questions to generate", "5")
         .option("--resume <id>", "Load a specific resume ID for context (from cv resumes list)")
         .option("--text", "Use text-only mode (no audio required)")
+        .option("--model <model>", "Specify a custom model to use for the interview session")
         .addHelpText("after", `
 Examples:
   cv interview
@@ -837,7 +907,7 @@ Voice mode setup (one-time):
         // ── Generate questions ───────────────────────────────────────────
         let questions;
         try {
-            questions = await generateQuestions(role, numQuestions);
+            questions = await generateQuestions(role, numQuestions, opts.model);
         }
         catch (err) {
             console.error(chalk.red(`\n  Failed to generate questions: ${err.message}\n`));
@@ -845,7 +915,7 @@ Voice mode setup (one-time):
         }
         // ── Determine mode ───────────────────────────────────────────────
         if (opts.text) {
-            await runTextSession({ role, questions, resumeContext });
+            await runTextSession({ role, questions, resumeContext, model: opts.model });
             return;
         }
         // Probe for sox
@@ -856,12 +926,12 @@ Voice mode setup (one-time):
                 "    macOS:  brew install sox\n" +
                 "    Linux:  sudo apt install sox\n" +
                 "\n  Or run in text mode:  cv interview --text\n"));
-            await runTextSession({ role, questions, resumeContext });
+            await runTextSession({ role, questions, resumeContext, model: opts.model });
             return;
         }
         // Voice mode
         try {
-            await runVoiceSession({ role, questions, resumeContext, soxPath });
+            await runVoiceSession({ role, questions, resumeContext, soxPath, model: opts.model });
         }
         catch (err) {
             console.error(chalk.red(`\n  Interview error: ${err.message}\n`));

package/dist/commands/jobs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../src/commands/jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkFpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,QAgjBnD"}
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../src/commands/jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmFpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,QAmtBnD"}

package/dist/commands/jobs.js

@@ -11,7 +11,7 @@ import { resolve } from "path";
 import chalk from "chalk";
 import ora from "ora";
 import boxen from "boxen";
-import { isApiError, resumeGet, jobsHunt, jobsCreate, jobsUpdate, jobsList, resumesList, generateCoverLetter, listCoverLetters, } from "../api.js";
+import { isApiError, resumeGet, jobsHunt, jobsCreate, jobsUpdate, jobsList, jobsDelete, resumesList, generateCoverLetter, listCoverLetters, } from "../api.js";
 import { checkGwsReady, runGwsCommand } from "../utils/gws-runner.js";
 import { printError } from "../output.js";
 import { registerApplyCommand } from "./apply.js";
@@ -323,15 +323,15 @@ export function registerJobsCommand(program) {
         .option("--json", "Output raw JSON")
         .action(async (opts) => {
         const isJson = opts.json ?? process.argv.includes("--json");
-        const spinner = ora("Fetching your job tracker…").start();
+        const spinner = isJson ? undefined : ora("Fetching your job tracker…").start();
         const result = await jobsList(opts.status);
         if (isApiError(result)) {
-            spinner.fail("Failed to fetch tracker.");
+            spinner?.fail("Failed to fetch tracker.");
             printError(result.message, undefined, isJson);
             process.exit(1);
         }
         const { jobs, total } = result;
-        spinner.succeed(`${total} job(s)${opts.status ? ` with status "${opts.status}"` : ""}`);
+        spinner?.succeed(`${total} job(s)${opts.status ? ` with status "${opts.status}"` : ""}`);
         if (isJson) {
             console.log(JSON.stringify(result));
             return;
@@ -354,6 +354,149 @@ export function registerJobsCommand(program) {
         console.log(`\n  ${statusSummary}\n`);
         console.log(chalk.dim(`  View on web: https://careervivid.app/job-tracker\n`));
     });
+    // ── cv jobs validate-links ───────────────────────────────────────────────
+    jobsCmd
+        .command("validate-links")
+        .description("Scan job tracker for duplicates, missing, generic, or broken links")
+        .option("--remove-stale", "Delete duplicates (keep oldest) and broken/missing/generic URL entries")
+        .option("--json", "Output raw JSON")
+        .action(async (opts) => {
+        const isJson = opts.json ?? process.argv.includes("--json");
+        const spinner = isJson ? undefined : ora("Fetching your job tracker…").start();
+        const listResult = await jobsList();
+        if (isApiError(listResult)) {
+            spinner?.fail("Failed to fetch tracker.");
+            printError(listResult.message, undefined, isJson);
+            process.exit(1);
+        }
+        const { jobs } = listResult;
+        spinner?.succeed(`Retrieved ${jobs.length} job(s) from tracker`);
+        if (jobs.length === 0) {
+            if (isJson) {
+                console.log(JSON.stringify({ jobs: [], duplicates: [], missing: [], generic: [], broken: [], removed: [], failed: [] }));
+            }
+            else {
+                console.log(chalk.yellow("\n  Your tracker is empty.\n"));
+            }
+            return;
+        }
+        const duplicates = [];
+        const missing = [];
+        const generic = [];
+        const broken = [];
+        const normalizeString = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+        const isFuzzyRoleMatch = (t1, t2) => {
+            const n1 = normalizeString(t1);
+            const n2 = normalizeString(t2);
+            if (n1 === n2)
+                return true;
+            if (n1.includes(n2) || n2.includes(n1))
+                return true;
+            // Fuzzy role check based on words of length >= 4
+            const w1 = t1.toLowerCase().split(/\s+/).filter(w => w.length >= 4);
+            const w2 = t2.toLowerCase().split(/\s+/).filter(w => w.length >= 4);
+            const intersection = w1.filter(w => w2.includes(w));
+            return intersection.length >= 2;
+        };
+        // Keep oldest entry: sort by updatedAt/createdAt asc (earliest first)
+        const sortedJobs = [...jobs].sort((a, b) => {
+            const t1 = a.updatedAt ? new Date(a.updatedAt).getTime() : 0;
+            const t2 = b.updatedAt ? new Date(b.updatedAt).getTime() : 0;
+            return t1 - t2;
+        });
+        const uniqueJobs = [];
+        for (const job of sortedJobs) {
+            const isDup = uniqueJobs.find(u => normalizeString(u.companyName) === normalizeString(job.companyName) &&
+                isFuzzyRoleMatch(u.jobTitle, job.jobTitle));
+            if (isDup) {
+                duplicates.push(job);
+            }
+            else {
+                uniqueJobs.push(job);
+            }
+        }
+        const { verifyUrl, isGenericJobLanding } = await import("../agent/tools/urlVerifier.js");
+        const checkSpinner = isJson ? undefined : ora("Verifying links…").start();
+        for (const job of uniqueJobs) {
+            const url = job.jobPostURL;
+            if (!url || url.trim() === "") {
+                missing.push(job);
+                continue;
+            }
+            if (isGenericJobLanding(url)) {
+                generic.push(job);
+                continue;
+            }
+            // Verify reachability
+            const ver = await verifyUrl(url);
+            if (!ver.ok) {
+                broken.push(job);
+            }
+        }
+        checkSpinner?.stop();
+        const toDelete = new Set();
+        duplicates.forEach(j => toDelete.add(j.id));
+        missing.forEach(j => toDelete.add(j.id));
+        generic.forEach(j => toDelete.add(j.id));
+        broken.forEach(j => toDelete.add(j.id));
+        const removed = [];
+        const failed = [];
+        if (opts.removeStale && toDelete.size > 0) {
+            const delSpinner = isJson ? undefined : ora(`Removing ${toDelete.size} stale/duplicate entries…`).start();
+            for (const id of toDelete) {
+                const res = await jobsDelete({ jobId: id });
+                if (isApiError(res)) {
+                    failed.push(`${id}: ${res.message}`);
+                }
+                else {
+                    removed.push(id);
+                }
+            }
+            delSpinner?.succeed(`Removed ${removed.length} entries (${failed.length} failed)`);
+        }
+        if (isJson) {
+            console.log(JSON.stringify({
+                totalFound: jobs.length,
+                duplicates: duplicates.map(j => ({ id: j.id, title: j.jobTitle, company: j.companyName })),
+                missing: missing.map(j => ({ id: j.id, title: j.jobTitle, company: j.companyName })),
+                generic: generic.map(j => ({ id: j.id, title: j.jobTitle, company: j.companyName, url: j.jobPostURL })),
+                broken: broken.map(j => ({ id: j.id, title: j.jobTitle, company: j.companyName, url: j.jobPostURL })),
+                removed,
+                failed
+            }));
+            return;
+        }
+        console.log(`\n${chalk.bold("  Job Tracker Audit Summary")}\n`);
+        if (duplicates.length > 0) {
+            console.log(chalk.yellow(`  👯 Duplicates (${duplicates.length}):`));
+            duplicates.forEach(j => console.log(chalk.dim(`    - ${j.jobTitle} @ ${j.companyName} (ID: ${j.id})`)));
+        }
+        if (missing.length > 0) {
+            console.log(chalk.yellow(`  🔗 Missing Apply Links (${missing.length}):`));
+            missing.forEach(j => console.log(chalk.dim(`    - ${j.jobTitle} @ ${j.companyName} (ID: ${j.id})`)));
+        }
+        if (generic.length > 0) {
+            console.log(chalk.yellow(`  🌐 Generic/Careers Landing URLs (${generic.length}):`));
+            generic.forEach(j => console.log(chalk.dim(`    - ${j.jobTitle} @ ${j.companyName}: ${j.jobPostURL} (ID: ${j.id})`)));
+        }
+        if (broken.length > 0) {
+            console.log(chalk.yellow(`  ❌ Broken/Expired URLs (${broken.length}):`));
+            broken.forEach(j => console.log(chalk.dim(`    - ${j.jobTitle} @ ${j.companyName}: ${j.jobPostURL} (ID: ${j.id})`)));
+        }
+        const totalStale = toDelete.size;
+        if (totalStale === 0) {
+            console.log(chalk.green("  ✔ No stale or duplicate job listings found in your tracker!\n"));
+        }
+        else {
+            console.log(`\n  Total stale entries found: ${chalk.bold.red(totalStale)}`);
+            if (opts.removeStale) {
+                console.log(chalk.green(`  ✔ Cleaned ${removed.length} entries successfully.\n`));
+            }
+            else {
+                console.log(chalk.cyan(`  💡 Run with ${chalk.bold("--remove-stale")} to automatically delete these entries.\n`));
+            }
+        }
+    });
     // ── cv jobs sync-gmail (legacy) ───────────────────────────────────────────
     jobsCmd
         .command("sync-gmail")

package/dist/commands/resumes.js

@@ -59,15 +59,15 @@ export function registerResumesCommand(program) {
         .option("--json", "Output raw JSON")
         .action(async (opts) => {
         const isJson = opts.json ?? process.argv.includes("--json");
-        const spinner = ora("Fetching resumes…").start();
+        const spinner = isJson ? undefined : ora("Fetching resumes…").start();
         const result = await resumesList();
         if (isApiError(result)) {
-            spinner.fail("Failed to list resumes.");
+            spinner?.fail("Failed to list resumes.");
             printError(result.message, undefined, isJson);
             process.exit(1);
         }
         const { resumes, total } = result;
-        spinner.succeed(`Found ${total} resume(s)`);
+        spinner?.succeed(`Found ${total} resume(s)`);
         if (isJson) {
             console.log(JSON.stringify(result));
             return;
@@ -90,14 +90,14 @@ export function registerResumesCommand(program) {
         .option("--json", "Output raw JSON")
         .action(async (id, opts) => {
         const isJson = opts.json ?? process.argv.includes("--json");
-        const spinner = ora("Fetching resume…").start();
+        const spinner = isJson ? undefined : ora("Fetching resume…").start();
         const result = await resumeGet(id);
         if (isApiError(result)) {
-            spinner.fail("Failed to get resume.");
+            spinner?.fail("Failed to get resume.");
             printError(result.message, undefined, isJson);
             process.exit(1);
         }
-        spinner.succeed(`Resume loaded: ${result.title}`);
+        spinner?.succeed(`Resume loaded: ${result.title}`);
         if (isJson) {
             console.log(JSON.stringify(result));
             return;

package/dist/index.js

@@ -98,10 +98,12 @@ async function main() {
         return;
     }
     // ── Session expiry check (firebase-cli style) ──────────────────────────────
-    // Skip for auth/login/logout/config/help commands — they don’t need a live session
+    // Skip for auth/login/logout/config/help commands — they don’t need a live session.
+    // Subcommand help must work before login, e.g. `cv agent --help`.
     const SESSION_EXEMPT = ["login", "logout", "auth", "config", "upgrade", "-v", "--version", "-h", "--help", "help"];
     const subcommand = process.argv[2] ?? "";
-    const isExempt = SESSION_EXEMPT.some((c) => subcommand === c || subcommand.startsWith(c));
+    const wantsHelp = process.argv.includes("-h") || process.argv.includes("--help") || subcommand === "help";
+    const isExempt = wantsHelp || SESSION_EXEMPT.includes(subcommand);
     if (!isExempt && !process.env.CV_API_KEY && !isSessionValid()) {
         const { loadConfig } = await import("./config.js");
         const hasKey = !!loadConfig().apiKey;