githits 0.2.2 → 0.3.0

package/dist/cli.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 import {
+  AuthConfigError,
+  AuthStoragePolicyError,
   AuthenticationError,
+  CLIENT_UPDATE_REQUIRED_REASON,
+  ClientUpdateRequiredError,
   CodeNavigationAccessError,
   CodeNavigationBackendError,
   CodeNavigationFeatureFlagRequiredError,
@@ -16,6 +20,7 @@ import {
   FileSystemServiceImpl,
   MalformedCodeNavigationResponseError,
   MalformedPackageIntelligenceResponseError,
+  NpmRegistryUpdateCheckService,
   PackageIntelligenceAccessError,
   PackageIntelligenceBackendError,
   PackageIntelligenceChangelogSourceNotFoundError,
@@ -26,30 +31,155 @@ import {
   PackageIntelligenceValidationError,
   PackageIntelligenceVersionNotFoundError,
   PromptServiceImpl,
+  createAuthCommandDependencies,
+  createAuthStatusDependencies,
   createContainer,
   debugLog,
   endTelemetrySpan,
   flushTelemetry,
-  getCodeNavigationCapability,
+  formatRequiredUpdateNotice,
+  formatUpdateNotice,
   getCodeNavigationUrl,
-  getEnvApiToken,
-  isCodeNavigationCliOverrideEnabled,
   isTelemetryEnabled,
   refreshExpiredToken,
-  resolveStartupCodeNavigationRegistrationState,
   setClientMode,
   setMcpClientVersionProvider,
+  shouldRunRequiredUpdateEnforcement,
+  shouldRunUpdateCheck,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-ns1j9dan.js";
+} from "./shared/chunk-5mk9k2gv.js";
 import {
   __require,
   version
-} from "./shared/chunk-g6ay6x9v.js";
+} from "./shared/chunk-gxya097b.js";
 
 // src/cli.ts
 import { Command } from "commander";
 
+// src/cli/update-check.ts
+function startUpdateCheckTask(service) {
+  const controller = new AbortController;
+  return {
+    promise: service.checkForUpdate(controller.signal),
+    abort: () => controller.abort()
+  };
+}
+function startRequiredUpdateRefreshTask(service) {
+  const controller = new AbortController;
+  return {
+    promise: service.refreshRequiredUpdateStatus(controller.signal),
+    abort: () => controller.abort()
+  };
+}
+function startUpdateCheckTaskForInvocation(options) {
+  if (!shouldRunUpdateCheck({
+    args: options.args,
+    env: options.env,
+    stderrIsTTY: options.stderrIsTTY,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY
+  })) {
+    return;
+  }
+  return startUpdateCheckTask(options.createService());
+}
+function startRequiredUpdateRefreshTaskForInvocation(options) {
+  if (!shouldRunRequiredUpdateEnforcement({
+    args: options.args,
+    env: options.env
+  })) {
+    return;
+  }
+  return startRequiredUpdateRefreshTask(options.createService());
+}
+async function enforceCachedRequiredUpdateForInvocation(options) {
+  if (!shouldRunRequiredUpdateEnforcement({
+    args: options.args,
+    env: options.env
+  })) {
+    return;
+  }
+  const notice = await options.createService().getRequiredUpdateNotice();
+  if (!notice) {
+    return;
+  }
+  if (isJsonInvocation(options.args)) {
+    options.stderr.write(`${JSON.stringify(requiredUpdateEnvelope(notice))}
+`);
+  } else {
+    options.stderr.write(`${formatRequiredUpdateNotice(notice)}
+`);
+  }
+  options.exit(1);
+}
+async function runWithUpdateCheckFlush(action, task, options) {
+  try {
+    return await action();
+  } finally {
+    await flushRequiredUpdateRefresh(options.requiredUpdateRefreshTask, {
+      timeoutMs: options.timeoutMs
+    });
+    await flushUpdateCheckNotice(task, options);
+  }
+}
+async function flushRequiredUpdateRefresh(task, options = {}) {
+  if (!task) {
+    return;
+  }
+  const timeoutMs = options.timeoutMs ?? 50;
+  let timeout;
+  const timeoutPromise = new Promise((resolve) => {
+    timeout = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  const result = await Promise.race([task.promise, timeoutPromise]);
+  if (timeout) {
+    clearTimeout(timeout);
+  }
+  if (result === "timeout") {
+    task.abort();
+  }
+}
+async function flushUpdateCheckNotice(task, options) {
+  if (!task) {
+    return;
+  }
+  const timeoutMs = options.timeoutMs ?? 50;
+  let timeout;
+  const timeoutPromise = new Promise((resolve) => {
+    timeout = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  const result = await Promise.race([task.promise, timeoutPromise]);
+  if (timeout) {
+    clearTimeout(timeout);
+  }
+  if (result === "timeout") {
+    task.abort();
+    return;
+  }
+  if (!result) {
+    return;
+  }
+  options.stderr.write(`${formatUpdateNotice(result)}
+`);
+}
+function isJsonInvocation(args) {
+  return args.includes("--json");
+}
+function requiredUpdateEnvelope(notice) {
+  return {
+    error: `Update required: ${notice.reason}`,
+    code: "UPDATE_REQUIRED",
+    retryable: false,
+    details: {
+      currentVersion: notice.currentVersion,
+      ...notice.latestKnownVersion ? { latestKnownVersion: notice.latestKnownVersion } : {},
+      updateCommand: notice.updateCommand,
+      reason: notice.reason
+    }
+  };
+}
+
 // src/commands/auth-status.ts
 function displayExpiry(expiresAt) {
   if (!expiresAt) {
@@ -65,23 +195,12 @@ function displayExpiry(expiresAt) {
     console.log(`  Expires: in ${minutesLeft} minute${minutesLeft !== 1 ? "s" : ""}`);
   }
 }
-function displayCodeNavigationStatus(capability, overrideEnabled) {
-  console.log(`  Code navigation: ${capability}`);
-  console.log(`  CLI override: ${overrideEnabled ? "enabled" : "disabled"}`);
-}
 async function authStatusAction(deps) {
-  const {
-    authStorage,
-    authService,
-    mcpUrl,
-    envApiToken,
-    codeNavigationCliOverrideEnabled
-  } = deps;
+  const { authStorage, authService, mcpUrl, envApiToken } = deps;
   if (envApiToken) {
     console.log(`Authenticated via environment variable.
 `);
     console.log(`  Source: GITHITS_API_TOKEN`);
-    displayCodeNavigationStatus(getCodeNavigationCapability(envApiToken), codeNavigationCliOverrideEnabled);
     return;
   }
   const auth = await authStorage.loadTokens(mcpUrl);
@@ -90,7 +209,6 @@ async function authStatusAction(deps) {
 `);
     console.log(`  Environment: ${mcpUrl}
 `);
-    displayCodeNavigationStatus("unknown", codeNavigationCliOverrideEnabled);
     console.log("");
     console.log("To authenticate:");
     console.log("  githits login");
@@ -100,12 +218,10 @@ async function authStatusAction(deps) {
     const refreshed = await refreshExpiredToken(authService, authStorage, mcpUrl);
     if (refreshed) {
       const refreshedAuth = await authStorage.loadTokens(mcpUrl);
-      const capability = getCodeNavigationCapability(refreshedAuth?.accessToken);
       console.log(`Authenticated (token refreshed).
 `);
       console.log(`  Environment: ${mcpUrl}`);
       displayExpiry(refreshedAuth?.expiresAt ?? null);
-      displayCodeNavigationStatus(capability, codeNavigationCliOverrideEnabled);
       console.log(`
   Storage: ${authStorage.getStorageLocation()}`);
       return;
@@ -115,7 +231,6 @@ async function authStatusAction(deps) {
     console.log(`  Environment: ${mcpUrl}`);
     console.log(`  Expired: ${new Date(auth.expiresAt).toLocaleDateString()}
 `);
-    displayCodeNavigationStatus("unknown", codeNavigationCliOverrideEnabled);
     console.log("");
     console.log("Run `githits login` to re-authenticate.");
     return;
@@ -124,35 +239,26 @@ async function authStatusAction(deps) {
 `);
   console.log(`  Environment: ${mcpUrl}`);
   displayExpiry(auth.expiresAt);
-  displayCodeNavigationStatus(getCodeNavigationCapability(auth.accessToken), codeNavigationCliOverrideEnabled);
   console.log(`
   Storage: ${authStorage.getStorageLocation()}`);
 }
 var STATUS_DESCRIPTION = `Show current authentication status.
 
 Displays details about the stored token including environment
-and expiration. Useful for debugging authentication issues.`;
+and expiration. If GITHITS_API_TOKEN is set, reports that source
+without reading local OAuth storage. Useful for debugging authentication issues.`;
 function registerAuthStatusCommand(program) {
   program.command("status").summary("Show authentication status").description(STATUS_DESCRIPTION).action(async () => {
-    const deps = await createContainer();
+    const deps = await createAuthStatusDependencies();
     await authStatusAction(deps);
   });
 }
 // src/commands/gated-command-group.ts
 async function resolveGatedCommandGroupRegistrationState(options = {}) {
   const codeNavigationUrl = options.codeNavigationUrl ?? getCodeNavigationUrl();
-  if (!codeNavigationUrl) {
-    return { codeNavigationUrl: undefined, shouldRegister: false };
-  }
-  const overrideEnabled = options.overrideEnabled ?? isCodeNavigationCliOverrideEnabled();
-  const registrationState = options.capability !== undefined || options.expiredStoredAuth !== undefined ? {
-    capability: options.capability ?? "unknown",
-    expiredStoredAuth: options.expiredStoredAuth ?? false
-  } : await resolveStartupCodeNavigationRegistrationState();
-  const envTokenPresent = options.envTokenPresent ?? Boolean(getEnvApiToken());
   return {
     codeNavigationUrl,
-    shouldRegister: overrideEnabled || registrationState.capability === "enabled" || envTokenPresent || registrationState.expiredStoredAuth
+    shouldRegister: codeNavigationUrl.length > 0
   };
 }
 
@@ -346,6 +452,9 @@ function mapCodeNavigationError(error2) {
   return mapped;
 }
 function classify(error2) {
+  if (error2 instanceof ClientUpdateRequiredError) {
+    return buildUpdateRequiredError(error2.reason, error2.currentVersion);
+  }
   if (error2 instanceof CodeNavigationVersionNotFoundError) {
     const details = {};
     if (error2.packageName)
@@ -456,6 +565,27 @@ function classify(error2) {
   }
   return { code: "UNKNOWN", message: "Unknown error", retryable: false };
 }
+function buildUpdateRequiredError(reason = CLIENT_UPDATE_REQUIRED_REASON, currentVersion) {
+  return {
+    code: "UPDATE_REQUIRED",
+    message: `Update required: ${reason}`,
+    retryable: false,
+    details: {
+      reason,
+      updateCommand: "npm i -g githits@latest",
+      ...currentVersion ? { currentVersion } : {}
+    }
+  };
+}
+function formatMappedErrorForTerminal(mapped) {
+  if (mapped.code !== "UPDATE_REQUIRED") {
+    return mapped.message;
+  }
+  const detail = mapped.details ?? {};
+  const updateCommand = typeof detail.updateCommand === "string" ? detail.updateCommand : "npm i -g githits@latest";
+  return [mapped.message, "", "Update with:", `  ${updateCommand}`].join(`
+`);
+}
 function classifyBackendError(error2) {
   const details = {};
   if (typeof error2.status === "number")
@@ -1146,12 +1276,280 @@ function mergeRanges(existing, incoming) {
 function clampCharacterOffset(text, offset) {
   return Math.max(0, Math.min(text.length, offset));
 }
+// src/shared/grep-repo-text.ts
+var SEP = " | ";
+function renderGrepRepoText(envelope) {
+  const lines = [];
+  lines.push(buildHeader(envelope));
+  lines.push("");
+  if (envelope.matches.length === 0) {
+    lines.push("No matches.");
+    const trailer2 = buildTrailer(envelope);
+    if (trailer2.length > 0) {
+      lines.push("");
+      for (const t of trailer2)
+        lines.push(t);
+    }
+    return lines.join(`
+`);
+  }
+  const blocks = buildRenderBlocks2(envelope.matches);
+  const blocksByFile = groupBlocksByFile2(blocks);
+  const useContext = blocksHaveContext(blocks);
+  const matchCountsByFile = countMatchesByFile(envelope.matches);
+  let firstFile = true;
+  for (const [filePath, fileBlocks] of blocksByFile) {
+    if (!firstFile)
+      lines.push("");
+    firstFile = false;
+    const matchCount = matchCountsByFile.get(filePath) ?? 0;
+    lines.push(`${filePath} (${matchCount})`);
+    fileBlocks.forEach((block, idx) => {
+      if (useContext && idx > 0)
+        lines.push("  --");
+      const gutterWidth = widestLineNumberInBlock(block);
+      for (const ln of block.lines) {
+        lines.push(renderLine(ln, gutterWidth, useContext));
+      }
+    });
+  }
+  const trailer = buildTrailer(envelope);
+  if (trailer.length > 0) {
+    lines.push("");
+    for (const t of trailer)
+      lines.push(t);
+  }
+  return lines.join(`
+`);
+}
+function buildHeader(envelope) {
+  const parts = [
+    `code_grep${SEP}${envelope.totalMatches} match${envelope.totalMatches === 1 ? "" : "es"} in ${envelope.uniqueFilesMatched} file${envelope.uniqueFilesMatched === 1 ? "" : "s"}`
+  ];
+  parts.push(`pattern=${quote(envelope.pattern)}`);
+  const flags = [];
+  if (envelope.patternType === "regex")
+    flags.push("regex");
+  if (envelope.caseSensitive)
+    flags.push("case-sensitive");
+  if (flags.length > 0)
+    parts.push(flags.join(","));
+  const filterEcho = buildFilterEcho(envelope);
+  if (filterEcho)
+    parts.push(filterEcho);
+  return parts.join(SEP);
+}
+function buildFilterEcho(envelope) {
+  const filter = envelope.filter;
+  if (!filter)
+    return "";
+  const parts = [];
+  if (filter.path)
+    parts.push(`path=${quote(filter.path)}`);
+  if (filter.pathPrefix)
+    parts.push(`path_prefix=${quote(filter.pathPrefix)}`);
+  if (filter.globs?.length)
+    parts.push(`globs=${filter.globs.join(",")}`);
+  if (filter.extensions?.length) {
+    parts.push(`exts=${filter.extensions.join(",")}`);
+  }
+  if (typeof filter.maxMatches === "number") {
+    parts.push(`max_matches=${filter.maxMatches}`);
+  }
+  if (typeof filter.maxMatchesPerFile === "number") {
+    parts.push(`max_matches_per_file=${filter.maxMatchesPerFile}`);
+  }
+  return parts.join(" ");
+}
+function buildTrailer(envelope) {
+  const lines = [];
+  if (envelope.truncatedReason) {
+    lines.push(`Truncated: ${envelope.truncatedReason}. Pass narrower path/path_prefix/globs or increase max_matches.`);
+  }
+  if (envelope.hasMore && envelope.nextCursor) {
+    lines.push(`More matches available. Pass cursor=${envelope.nextCursor} for the next page.`);
+  } else if (envelope.hasMore) {
+    lines.push("More matches available.");
+  }
+  const skipNotes = [];
+  if (envelope.binaryFilesSkipped) {
+    skipNotes.push(`${envelope.binaryFilesSkipped} binary file(s) skipped`);
+  }
+  if (envelope.filesTooLargeSkipped) {
+    skipNotes.push(`${envelope.filesTooLargeSkipped} oversized file(s) skipped`);
+  }
+  if (skipNotes.length > 0) {
+    lines.push(`Note: ${skipNotes.join(", ")}.`);
+  }
+  return lines;
+}
+function buildRenderBlocks2(matches) {
+  if (matches.length === 0)
+    return [];
+  const linesByFile = new Map;
+  for (const match of matches) {
+    let lineMap = linesByFile.get(match.filePath);
+    if (!lineMap) {
+      lineMap = new Map;
+      linesByFile.set(match.filePath, lineMap);
+    }
+    const before = match.contextBefore ?? [];
+    const beforeStart = match.line - before.length;
+    for (let i = 0;i < before.length; i += 1) {
+      const lineNumber = beforeStart + i;
+      if (!lineMap.has(lineNumber)) {
+        lineMap.set(lineNumber, {
+          lineNumber,
+          content: before[i] ?? "",
+          isMatch: false
+        });
+      }
+    }
+    lineMap.set(match.line, {
+      lineNumber: match.line,
+      content: match.lineContent,
+      isMatch: true
+    });
+    const after = match.contextAfter ?? [];
+    for (let i = 0;i < after.length; i += 1) {
+      const lineNumber = match.line + i + 1;
+      if (!lineMap.has(lineNumber)) {
+        lineMap.set(lineNumber, {
+          lineNumber,
+          content: after[i] ?? "",
+          isMatch: false
+        });
+      }
+    }
+  }
+  const blocks = [];
+  for (const [filePath, lineMap] of linesByFile) {
+    const sorted = [...lineMap.values()].sort((a, b) => a.lineNumber - b.lineNumber);
+    let current = [];
+    for (const line of sorted) {
+      const previous = current[current.length - 1];
+      if (!previous || line.lineNumber === previous.lineNumber + 1) {
+        current.push(line);
+        continue;
+      }
+      blocks.push({ filePath, lines: current });
+      current = [line];
+    }
+    if (current.length > 0) {
+      blocks.push({ filePath, lines: current });
+    }
+  }
+  return blocks;
+}
+function groupBlocksByFile2(blocks) {
+  const map = new Map;
+  for (const block of blocks) {
+    const list = map.get(block.filePath) ?? [];
+    list.push(block);
+    map.set(block.filePath, list);
+  }
+  return map;
+}
+function blocksHaveContext(blocks) {
+  for (const block of blocks) {
+    for (const line of block.lines) {
+      if (!line.isMatch)
+        return true;
+    }
+  }
+  return false;
+}
+function widestLineNumberInBlock(block) {
+  let max = 0;
+  for (const line of block.lines) {
+    const len = String(line.lineNumber).length;
+    if (len > max)
+      max = len;
+  }
+  return max;
+}
+function countMatchesByFile(matches) {
+  const counts = new Map;
+  for (const match of matches) {
+    counts.set(match.filePath, (counts.get(match.filePath) ?? 0) + 1);
+  }
+  return counts;
+}
+function renderLine(line, gutterWidth, useContext) {
+  const gutter = String(line.lineNumber).padStart(gutterWidth, " ");
+  const sep = !useContext || line.isMatch ? ":" : "-";
+  return `  ${gutter}${sep} ${line.content}`;
+}
+function quote(value) {
+  return value.includes('"') ? `'${value}'` : `"${value}"`;
+}
 // src/shared/language-filter.ts
 var DEFAULT_LIMIT = 5;
 function filterLanguages(languages, query, limit = DEFAULT_LIMIT) {
   const lowerQuery = query.toLowerCase();
   return languages.filter((lang) => lang.name.toLowerCase().includes(lowerQuery) || lang.display_name.toLowerCase().includes(lowerQuery) || lang.aliases.some((a) => a.toLowerCase().includes(lowerQuery))).slice(0, limit).map(({ name, display_name }) => ({ name, display_name }));
 }
+// src/shared/list-files-text.ts
+var SEP2 = " | ";
+function renderListFilesText(envelope) {
+  const lines = [];
+  lines.push(buildHeader2(envelope));
+  lines.push("");
+  if (envelope.files.length === 0) {
+    lines.push(envelope.hint ?? "No files match the requested filter.");
+    return lines.join(`
+`);
+  }
+  for (const entry of envelope.files) {
+    lines.push(entry.path);
+  }
+  if (envelope.hasMore) {
+    lines.push("");
+    lines.push("More files available. Pass limit=N to widen or refine path_prefix.");
+  }
+  if (envelope.hint) {
+    lines.push("");
+    lines.push(envelope.hint);
+  }
+  return lines.join(`
+`);
+}
+function buildHeader2(envelope) {
+  const identity = buildIdentity(envelope);
+  const countValue = envelope.hasMore ? `${envelope.files.length}+` : String(envelope.total);
+  const parts = [
+    `code_files${SEP2}${countValue} path${countValue === "1" ? "" : "s"}`
+  ];
+  if (identity)
+    parts.push(identity);
+  const filter = buildFilterEcho2(envelope);
+  if (filter)
+    parts.push(filter);
+  return parts.join(SEP2);
+}
+function buildIdentity(envelope) {
+  if (envelope.registry && envelope.name) {
+    const version2 = envelope.indexedVersion ?? envelope.resolution?.resolvedRef;
+    return version2 ? `${envelope.registry}:${envelope.name}@${version2}` : `${envelope.registry}:${envelope.name}`;
+  }
+  if (envelope.repoUrl) {
+    return envelope.gitRef ? `${envelope.repoUrl}@${envelope.gitRef}` : envelope.repoUrl;
+  }
+  return "";
+}
+function buildFilterEcho2(envelope) {
+  const parts = [];
+  if (envelope.filter?.pathPrefix) {
+    parts.push(`path_prefix=${quote2(envelope.filter.pathPrefix)}`);
+  }
+  if (envelope.filter?.limit !== undefined) {
+    parts.push(`limit=${envelope.filter.limit}`);
+  }
+  return parts.join(" ");
+}
+function quote2(value) {
+  return value.includes('"') ? `'${value}'` : `"${value}"`;
+}
 // src/shared/list-package-docs-request.ts
 function buildListPackageDocsParams(input) {
   const packageName = input.packageName?.trim() ?? "";
@@ -2037,6 +2435,9 @@ function mapPackageIntelligenceError(error2) {
   return mapped;
 }
 function classify2(error2) {
+  if (error2 instanceof ClientUpdateRequiredError) {
+    return buildUpdateRequiredError(error2.reason, error2.currentVersion);
+  }
   if (error2 instanceof PackageIntelligenceTargetNotFoundError || error2 instanceof PackageIntelligenceChangelogSourceNotFoundError) {
     return {
       code: "NOT_FOUND",
@@ -2596,19 +2997,20 @@ function isSeverityLabel(value) {
 function buildPackageVulnerabilitiesSuccessPayload(report, options = {}) {
   const pkg = report.package;
   const security = report.security;
-  const total = security?.vulnerabilityCount ?? 0;
+  const dedupedAdvisories = dedupAdvisoriesByAlias(security?.vulnerabilities ?? []);
+  const total = security?.affectedVulnerabilityCount ?? dedupedAdvisories.length;
   const payload = {
     registry: lowerRegistry3(pkg.registry),
     name: pkg.name,
     version: pkg.version,
-    summary: buildSummary(total, security)
+    summary: buildSummary(total, security, dedupedAdvisories)
   };
   const requestedEcho = deriveRequestedVersion2(options.requestedVersion, pkg.version);
   if (requestedEcho !== undefined) {
     payload.requestedVersion = requestedEcho;
   }
   if (total > 0) {
-    const sortedAdvisories = sortAdvisories((security?.vulnerabilities ?? []).map(buildAdvisory));
+    const sortedAdvisories = sortAdvisories(dedupedAdvisories.map(buildAdvisory));
     if (sortedAdvisories.length > 0) {
       payload.advisories = sortedAdvisories;
     }
@@ -2647,14 +3049,19 @@ function parseVersionForSort(v) {
   });
   return { main, pre };
 }
-function buildSummary(total, security) {
+function buildSummary(total, security, dedupedAdvisories) {
   const summary = { total };
-  if (total === 0)
-    return summary;
+  if (security) {
+    summary.affectedVulnerabilityCount = security.affectedVulnerabilityCount;
+    summary.nonAffectingVulnerabilityCount = security.nonAffectingVulnerabilityCount;
+    summary.allVulnerabilityCount = security.allVulnerabilityCount;
+  }
   if (typeof security?.currentVersionAffected === "boolean") {
     summary.affected = security.currentVersionAffected;
   }
-  const bySeverity = computeBySeverity(security?.vulnerabilities ?? []);
+  if (total === 0)
+    return summary;
+  const bySeverity = computeBySeverity(dedupedAdvisories);
   const anyCounted = Object.values(bySeverity).some((n) => n > 0);
   if (anyCounted) {
     const trimmed = {};
@@ -2709,6 +3116,231 @@ function vulnSeverityLabel(score) {
     return "medium";
   return "low";
 }
+function dedupAdvisoriesByAlias(advisories) {
+  if (advisories.length === 0)
+    return [];
+  const parent = new Map;
+  const find = (id) => {
+    let root = id;
+    let next = parent.get(root);
+    while (next !== undefined && next !== root) {
+      root = next;
+      next = parent.get(root);
+    }
+    let cursor = id;
+    while (cursor !== root) {
+      const parentOfCursor = parent.get(cursor);
+      if (parentOfCursor === undefined)
+        break;
+      parent.set(cursor, root);
+      cursor = parentOfCursor;
+    }
+    return root;
+  };
+  const union = (a, b) => {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb)
+      parent.set(ra, rb);
+  };
+  const ensure = (id) => {
+    if (!parent.has(id))
+      parent.set(id, id);
+  };
+  const advisoryKeys = [];
+  for (let i = 0;i < advisories.length; i++) {
+    const advisory = advisories[i];
+    if (!advisory) {
+      advisoryKeys.push(`__synthetic_${i}`);
+      continue;
+    }
+    const ids = [];
+    if (advisory.osvId)
+      ids.push(advisory.osvId);
+    for (const alias of advisory.aliases ?? []) {
+      if (alias)
+        ids.push(alias);
+    }
+    if (ids.length === 0) {
+      const synthetic = `__synthetic_${i}`;
+      ensure(synthetic);
+      advisoryKeys.push(synthetic);
+      continue;
+    }
+    for (const id of ids)
+      ensure(id);
+    for (let j = 1;j < ids.length; j++) {
+      const a = ids[j - 1];
+      const b = ids[j];
+      if (a !== undefined && b !== undefined)
+        union(a, b);
+    }
+    advisoryKeys.push(ids[0]);
+  }
+  const clusters = new Map;
+  for (let i = 0;i < advisories.length; i++) {
+    const advisory = advisories[i];
+    if (!advisory)
+      continue;
+    const key = advisoryKeys[i];
+    if (key === undefined)
+      continue;
+    const root = find(key);
+    const bucket = clusters.get(root);
+    if (bucket)
+      bucket.push(advisory);
+    else
+      clusters.set(root, [advisory]);
+  }
+  const merged = [];
+  for (const cluster of clusters.values()) {
+    merged.push(mergeAdvisoryCluster(cluster));
+  }
+  return merged;
+}
+function mergeAdvisoryCluster(cluster) {
+  if (cluster.length === 1) {
+    const only = cluster[0];
+    if (!only)
+      throw new Error("empty advisory cluster");
+    return only;
+  }
+  const canonical = pickCanonical(cluster);
+  const aliasSet = new Set;
+  for (const member of cluster) {
+    if (member.osvId)
+      aliasSet.add(member.osvId);
+    for (const alias of member.aliases ?? []) {
+      if (alias)
+        aliasSet.add(alias);
+    }
+  }
+  if (canonical.osvId)
+    aliasSet.delete(canonical.osvId);
+  const aliases = Array.from(aliasSet).sort();
+  const affectedRangesSet = new Set;
+  const matchedAffectedRangesSet = new Set;
+  const fixedInSet = new Set;
+  const duplicateIdsSet = new Set;
+  let isMalicious = false;
+  let affectsInspectedVersion = false;
+  let affectedVersionRangesTruncated = false;
+  let affectedVersionRangesCount = 0;
+  let latestModifiedAt = canonical.modifiedAt;
+  let withdrawnAt;
+  let allWithdrawn = true;
+  let maxSeverityScore = typeof canonical.severityScore === "number" ? canonical.severityScore : 0;
+  for (const member of cluster) {
+    for (const range of member.affectedVersionRanges ?? []) {
+      affectedRangesSet.add(range);
+    }
+    for (const range of member.matchedAffectedVersionRanges ?? []) {
+      matchedAffectedRangesSet.add(range);
+    }
+    for (const fix of member.fixedInVersions ?? []) {
+      fixedInSet.add(fix);
+    }
+    for (const duplicateId of member.duplicateIds ?? []) {
+      duplicateIdsSet.add(duplicateId);
+    }
+    if (member.isMalicious === true)
+      isMalicious = true;
+    if (member.affectsInspectedVersion === true)
+      affectsInspectedVersion = true;
+    if (member.affectedVersionRangesTruncated === true) {
+      affectedVersionRangesTruncated = true;
+    }
+    if (typeof member.affectedVersionRangesCount === "number") {
+      affectedVersionRangesCount = Math.max(affectedVersionRangesCount, member.affectedVersionRangesCount);
+    }
+    if (member.modifiedAt) {
+      if (!latestModifiedAt || member.modifiedAt > latestModifiedAt) {
+        latestModifiedAt = member.modifiedAt;
+      }
+    }
+    if (member.withdrawnAt) {
+      if (!withdrawnAt || member.withdrawnAt > withdrawnAt) {
+        withdrawnAt = member.withdrawnAt;
+      }
+    } else {
+      allWithdrawn = false;
+    }
+    if (!member.withdrawnAt && typeof member.severityScore === "number" && member.severityScore > maxSeverityScore) {
+      maxSeverityScore = member.severityScore;
+    }
+  }
+  const merged = {
+    ...canonical,
+    aliases
+  };
+  if (maxSeverityScore > 0) {
+    merged.severityScore = maxSeverityScore;
+  }
+  if (affectedRangesSet.size > 0) {
+    merged.affectedVersionRanges = Array.from(affectedRangesSet);
+  }
+  const exactOrLowerBoundCount = Math.max(affectedVersionRangesCount, affectedRangesSet.size);
+  if (exactOrLowerBoundCount > 0) {
+    merged.affectedVersionRangesCount = exactOrLowerBoundCount;
+  }
+  if (affectedVersionRangesTruncated) {
+    merged.affectedVersionRangesTruncated = true;
+  }
+  if (matchedAffectedRangesSet.size > 0) {
+    merged.matchedAffectedVersionRanges = Array.from(matchedAffectedRangesSet);
+  }
+  if (affectsInspectedVersion)
+    merged.affectsInspectedVersion = true;
+  if (duplicateIdsSet.size > 0) {
+    merged.duplicateIds = Array.from(duplicateIdsSet).sort();
+  }
+  if (fixedInSet.size > 0) {
+    merged.fixedInVersions = Array.from(fixedInSet);
+  }
+  if (isMalicious)
+    merged.isMalicious = true;
+  if (latestModifiedAt) {
+    merged.modifiedAt = latestModifiedAt;
+  } else {
+    delete merged.modifiedAt;
+  }
+  if (allWithdrawn && withdrawnAt) {
+    merged.withdrawnAt = withdrawnAt;
+  } else {
+    delete merged.withdrawnAt;
+  }
+  return merged;
+}
+function pickCanonical(cluster) {
+  const ranked = cluster.slice().sort((a, b) => {
+    const aHasScore = typeof a.severityScore === "number" && a.severityScore > 0 ? 1 : 0;
+    const bHasScore = typeof b.severityScore === "number" && b.severityScore > 0 ? 1 : 0;
+    if (aHasScore !== bHasScore)
+      return bHasScore - aHasScore;
+    const aRank = idPrefixRank(a.osvId);
+    const bRank = idPrefixRank(b.osvId);
+    if (aRank !== bRank)
+      return aRank - bRank;
+    const aId = a.osvId ?? "";
+    const bId = b.osvId ?? "";
+    if (aId !== bId)
+      return aId < bId ? -1 : 1;
+    return 0;
+  });
+  const winner = ranked[0];
+  if (!winner)
+    throw new Error("empty cluster passed to pickCanonical");
+  return winner;
+}
+function idPrefixRank(id) {
+  if (!id)
+    return 99;
+  if (id.startsWith("GHSA-"))
+    return 0;
+  if (id.startsWith("RUSTSEC-"))
+    return 2;
+  return 1;
+}
 function buildAdvisory(advisory) {
   const lean = {};
   if (advisory.osvId)
@@ -2728,6 +3360,21 @@ function buildAdvisory(advisory) {
   if (advisory.affectedVersionRanges && advisory.affectedVersionRanges.length > 0) {
     lean.affectedRanges = advisory.affectedVersionRanges.slice();
   }
+  if (typeof advisory.affectedVersionRangesCount === "number") {
+    lean.affectedVersionRangesCount = advisory.affectedVersionRangesCount;
+  }
+  if (advisory.affectedVersionRangesTruncated === true) {
+    lean.affectedVersionRangesTruncated = true;
+  }
+  if (typeof advisory.affectsInspectedVersion === "boolean") {
+    lean.affectsInspectedVersion = advisory.affectsInspectedVersion;
+  }
+  if (advisory.matchedAffectedVersionRanges && advisory.matchedAffectedVersionRanges.length > 0) {
+    lean.matchedAffectedVersionRanges = advisory.matchedAffectedVersionRanges.slice();
+  }
+  if (advisory.duplicateIds && advisory.duplicateIds.length > 0) {
+    lean.duplicateIds = advisory.duplicateIds.slice();
+  }
   if (advisory.fixedInVersions && advisory.fixedInVersions.length > 0) {
     lean.fixedIn = advisory.fixedInVersions.slice();
   }
@@ -2810,7 +3457,7 @@ function formatPackageVulnerabilitiesTerminal(report, options = {}) {
     const lines = [headerLine];
     if (requestedLine)
       lines.push(requestedLine);
-    lines.push("No known vulnerabilities.");
+    lines.push(formatNoAffectedVulnerabilitiesLine(payload));
     return `${lines.join(`
 `)}
 `;
@@ -2844,15 +3491,25 @@ function formatHeader(payload, useColors) {
 function formatSummaryLine(payload, useColors) {
   const n = payload.summary.total;
   const noun = n === 1 ? "vulnerability" : "vulnerabilities";
-  const base = `${n} known ${noun}`;
+  const verb = n === 1 ? "affects" : "affect";
+  const base = `${n} ${noun} ${verb} this version`;
   if (payload.summary.affected === true) {
-    return colorize(`${base} · latest affected`, "yellow", useColors);
+    return colorize(base, "yellow", useColors);
   }
   if (payload.summary.affected === false) {
-    return `${base} · latest clean`;
+    return base;
   }
   return base;
 }
+function formatNoAffectedVulnerabilitiesLine(payload) {
+  const historical = payload.summary.nonAffectingVulnerabilityCount ?? 0;
+  if (historical > 0) {
+    const noun = historical === 1 ? "historical advisory" : "historical advisories";
+    const verb = historical === 1 ? "does" : "do";
+    return `No vulnerabilities affect this version (${historical} ${noun} ${verb} not apply).`;
+  }
+  return "No known vulnerabilities affect this version.";
+}
 function formatBreakdownLine(summary, useColors) {
   if (summary.total <= 1)
     return;
@@ -2938,7 +3595,7 @@ function formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimi
     lines.push(`    ${label.padEnd(detailWidth)} ${value}`);
   };
   if (advisory.affectedRanges && advisory.affectedRanges.length > 0) {
-    pushRow("affected", formatRangeList(advisory.affectedRanges, verbose, useColors, rangeLimit));
+    pushRow("affected", formatRangeList(advisory.affectedRanges, verbose, useColors, rangeLimit, advisory.affectedVersionRangesCount, advisory.affectedVersionRangesTruncated));
   }
   if (advisory.fixedIn && advisory.fixedIn.length > 0) {
     pushRow("fixed in", advisory.fixedIn.join(", "));
@@ -2965,13 +3622,23 @@ function formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimi
   }
   return lines;
 }
-function formatRangeList(ranges, verbose, useColors, limit) {
+function formatRangeList(ranges, verbose, useColors, limit, totalCount, backendTruncated) {
+  const actualTotal = Math.max(totalCount ?? ranges.length, ranges.length);
+  const backendHidden = backendTruncated === true ? actualTotal - ranges.length : 0;
+  const appendBackendHint = (shown2) => {
+    if (backendHidden > 0) {
+      const hint2 = dim(`… (+${backendHidden} ranges omitted by service)`, useColors);
+      return shown2.length > 0 ? `${shown2}, ${hint2}` : hint2;
+    }
+    return shown2;
+  };
   if (verbose || ranges.length <= limit) {
-    return ranges.join(", ");
+    return appendBackendHint(ranges.join(", "));
   }
   const shown = ranges.slice(0, limit).join(", ");
-  const hiddenCount = ranges.length - limit;
-  const hint = dim(`… (+${hiddenCount} more; use -v)`, useColors);
+  const localHidden = ranges.length - limit;
+  const hintText = backendHidden > 0 ? `… (+${localHidden} more with -v; +${backendHidden} omitted by service)` : `… (+${localHidden} more; use -v)`;
+  const hint = dim(hintText, useColors);
   return `${shown}, ${hint}`;
 }
 function resolveAffectedRangesLimit(terminalWidth) {
@@ -2986,8 +3653,8 @@ function formatUpgradeFooter(paths) {
   if (!paths || paths.length === 0)
     return;
   if (paths.length === 1)
-    return `Upgrade to ${paths[0]}.`;
-  return `Upgrade options: ${paths.join(", ")}.`;
+    return `Fix version: ${paths[0]}.`;
+  return `Fix versions: ${paths.join(", ")}.`;
 }
 // src/shared/parse-lines-option.ts
 function parseLinesOption(raw) {
@@ -3114,7 +3781,7 @@ function formatReadPackageDocTerminal(envelope, options) {
     return envelope.content ?? "";
   }
   const lines = [];
-  lines.push(buildHeader(envelope, options.useColors));
+  lines.push(buildHeader3(envelope, options.useColors));
   lines.push(`pageId: ${envelope.pageId}`);
   if (envelope.sourceUrl)
     lines.push(`source: ${envelope.sourceUrl}`);
@@ -3134,7 +3801,7 @@ function formatReadPackageDocTerminal(envelope, options) {
 `)}
 `;
 }
-function buildHeader(envelope, useColors) {
+function buildHeader3(envelope, useColors) {
   const badge = envelope.sourceKind === "repo" ? "[repo]" : "[crawled]";
   const title = envelope.title ?? envelope.pageId;
   const prefix = envelope.registry && envelope.name ? `${envelope.registry}:${envelope.name}${envelope.version ? `@${envelope.version}` : ""}` : "documentation";
@@ -3167,10 +3834,11 @@ Need help? support@githits.com`);
   throw new AuthRequiredError(`Authentication required${suffix}`);
 }
 // src/shared/unified-search-request.ts
+var DEFAULT_UNIFIED_SEARCH_LIMIT = 10;
 function buildUnifiedSearchParams(input) {
   const targets = resolveTargets(input.target, input.targets);
   const rawQuery = normaliseRequiredQuery(input.query);
-  const limit = input.limit ?? 20;
+  const limit = input.limit ?? DEFAULT_UNIFIED_SEARCH_LIMIT;
   const offset = input.offset ?? 0;
   const waitTimeoutMs = input.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
   const qualifierClauses = buildQualifierClauses({
@@ -3276,7 +3944,7 @@ function buildFilters(input) {
   return Object.keys(filters).length > 0 ? filters : undefined;
 }
 // src/shared/unified-search-response.ts
-var DEFAULT_LIMIT2 = 20;
+var DEFAULT_LIMIT2 = DEFAULT_UNIFIED_SEARCH_LIMIT;
 var DEFAULT_OFFSET = 0;
 function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, outcome) {
   const warnings = outcome.state === "completed" ? outcome.result.queryWarnings : outcome.result?.queryWarnings ?? outcome.progress?.queryWarnings ?? [];
@@ -3299,6 +3967,9 @@ function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, outco
     const sourceStatus2 = compactSourceStatus(result?.sourceStatus);
     if (sourceStatus2)
       payload.sourceStatus = sourceStatus2;
+    const combinedWarnings2 = combineWarnings(warnings, sourceStatus2);
+    if (combinedWarnings2.length > 0)
+      payload.warnings = combinedWarnings2;
     return payload;
   }
   const completed = {
@@ -3315,8 +3986,18 @@ function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, outco
   const sourceStatus = compactSourceStatus(outcome.result.sourceStatus);
   if (sourceStatus)
     completed.sourceStatus = sourceStatus;
+  const combinedWarnings = combineWarnings(warnings, sourceStatus);
+  if (combinedWarnings.length > 0)
+    completed.warnings = combinedWarnings;
   return completed;
 }
+function combineWarnings(parserWarnings, sourceStatus) {
+  const out = [];
+  if (parserWarnings.length > 0)
+    out.push(...parserWarnings);
+  out.push(...buildSourceStatusWarnings(sourceStatus));
+  return out;
+}
 function buildUnifiedSearchErrorPayload(error2) {
   const mapped = mapCodeNavigationError(error2);
   const payload = {
@@ -3361,15 +4042,16 @@ function buildUnifiedSearchStatusResultPayload(result) {
   if (result.page.hasMore) {
     payload.nextOffset = result.page.offset + result.page.returned;
   }
-  if (result.queryWarnings.length > 0) {
-    payload.warnings = result.queryWarnings;
-  }
   if (result.sources.length > 0) {
     payload.sources = result.sources.map((entry) => entry.toLowerCase());
   }
   const sourceStatus = compactSourceStatus(result.sourceStatus);
   if (sourceStatus)
     payload.sourceStatus = sourceStatus;
+  const combinedWarnings = combineWarnings(result.queryWarnings, sourceStatus);
+  if (combinedWarnings.length > 0) {
+    payload.warnings = combinedWarnings;
+  }
   return payload;
 }
 function buildQueryEcho(params, rawQuery, compiledQuery, warnings) {
@@ -3495,6 +4177,46 @@ function compactProgress(progress) {
     payload.expiresAt = progress.expiresAt;
   return payload;
 }
+function buildSourceStatusWarnings(sourceStatus) {
+  if (!sourceStatus || sourceStatus.length === 0)
+    return [];
+  const warnings = [];
+  for (const entry of sourceStatus) {
+    const message = warningForEntry(entry);
+    if (message !== undefined)
+      warnings.push(message);
+  }
+  return warnings;
+}
+function warningForEntry(entry) {
+  const reasons = [];
+  if (entry.incompatibleQueryFeatures?.length) {
+    reasons.push(`incompatible query features [${entry.incompatibleQueryFeatures.join(", ")}]`);
+  }
+  if (entry.ignoredQueryFeatures?.length) {
+    reasons.push(`ignored query features [${entry.ignoredQueryFeatures.join(", ")}]`);
+  }
+  if (entry.incompatibleFilters?.length) {
+    reasons.push(`incompatible filters [${entry.incompatibleFilters.join(", ")}]`);
+  }
+  if (entry.ignoredFilters?.length) {
+    reasons.push(`ignored filters [${entry.ignoredFilters.join(", ")}]`);
+  }
+  if (entry.indexingStatus) {
+    reasons.push(`indexing status ${entry.indexingStatus}`);
+  }
+  if (entry.codeIndexState) {
+    reasons.push(`code index state ${entry.codeIndexState}`);
+  }
+  const prefix = `Source '${entry.source}' for ${entry.targetLabel}`;
+  if (reasons.length > 0) {
+    return `${prefix}: ${reasons.join("; ")}`;
+  }
+  if (entry.note) {
+    return `${prefix}: ${entry.note}`;
+  }
+  return;
+}
 function compactSourceStatus(sourceStatus) {
   if (!sourceStatus || sourceStatus.length === 0)
     return;
@@ -3581,6 +4303,194 @@ function parseRepoTarget(spec) {
   }
   return { repoUrl, gitRef };
 }
+// src/shared/unified-search-text.ts
+var SUMMARY_WRAP_WIDTH = 76;
+var SEP3 = " | ";
+function renderUnifiedSearchSuccess(payload) {
+  const lines = [];
+  lines.push(buildHeader4(payload));
+  lines.push("");
+  if (payload.results.length === 0) {
+    lines.push(payload.completed ? "No hits." : "No hits yet - indexing.");
+  } else {
+    payload.results.forEach((hit, idx) => {
+      if (idx > 0)
+        lines.push("");
+      appendHit(lines, idx + 1, hit);
+    });
+  }
+  const trailer = buildTrailer2(payload);
+  if (trailer.length > 0) {
+    lines.push("");
+    for (const line of trailer)
+      lines.push(line);
+  }
+  return lines.join(`
+`);
+}
+function renderUnifiedSearchError(payload) {
+  const lines = [];
+  const header = `search${SEP3}ERROR${SEP3}code=${payload.code}${payload.retryable ? `${SEP3}retryable` : ""}`;
+  lines.push(header);
+  lines.push(payload.error);
+  if (payload.details && Object.keys(payload.details).length > 0) {
+    lines.push("");
+    lines.push("details:");
+    for (const [key, value] of Object.entries(payload.details)) {
+      lines.push(`  ${key}: ${formatDetailValue(value)}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function buildHeader4(payload) {
+  const count = payload.results.length;
+  const status = payload.completed ? `${count} hit${count === 1 ? "" : "s"}` : `${count} partial`;
+  const parts = [`search${SEP3}${status}`];
+  parts.push(`query=${quote3(payload.query.raw)}`);
+  if (!payload.completed) {
+    parts.push(`searchRef=${payload.searchRef}`);
+  }
+  return parts.join(SEP3);
+}
+function appendHit(lines, index, hit) {
+  const headerParts = [hit.target, shortType(hit.type)];
+  if (typeof hit.score === "number") {
+    headerParts.push(formatScore(hit.score));
+  }
+  lines.push(`[${index}] ${headerParts.join("  ")}`);
+  const locator = buildLocatorLine(hit);
+  if (locator)
+    lines.push(`    ${locator}`);
+  if (hit.title && hit.title !== hit.locator.filePath) {
+    lines.push(`    ${hit.title}`);
+  }
+  if (hit.summary) {
+    for (const wrapped of wrapText2(hit.summary, SUMMARY_WRAP_WIDTH)) {
+      lines.push(`    ${wrapped}`);
+    }
+  }
+}
+function shortType(type) {
+  switch (type) {
+    case "repository_code":
+      return "code";
+    case "repository_symbol":
+      return "symbol";
+    case "documentation_page":
+      return "docs";
+    case "repository_doc":
+      return "repo-docs";
+    default:
+      return type;
+  }
+}
+function buildLocatorLine(hit) {
+  const loc = hit.locator;
+  if (loc.filePath) {
+    let line = `${loc.filePath}${formatLineRange(loc.startLine, loc.endLine)}`;
+    const tail = [];
+    if (loc.qualifiedPath)
+      tail.push(loc.qualifiedPath);
+    if (loc.kind)
+      tail.push(loc.kind);
+    if (tail.length > 0)
+      line += `  ${tail.join(SEP3)}`;
+    return line;
+  }
+  if (loc.pageId)
+    return `pageId: ${loc.pageId}`;
+  if (loc.sourceUrl)
+    return loc.sourceUrl;
+  return "";
+}
+function formatLineRange(start, end) {
+  if (typeof start !== "number")
+    return "";
+  if (typeof end !== "number" || end === start)
+    return `:${start}`;
+  return `:${start}-${end}`;
+}
+function formatScore(score) {
+  return score.toFixed(2);
+}
+function buildTrailer2(payload) {
+  const lines = [];
+  if (payload.warnings && payload.warnings.length > 0) {
+    lines.push("warnings:");
+    for (const warning2 of payload.warnings) {
+      lines.push(`  - ${warning2}`);
+    }
+  }
+  if (payload.hasMore) {
+    const nextOffsetHint = typeof payload.nextOffset === "number" ? ` Pass offset=${payload.nextOffset} for the next page or limit=N to widen.` : " Pass limit=N to widen.";
+    lines.push(`More hits available.${nextOffsetHint}`);
+  }
+  if (!payload.completed && payload.searchRef) {
+    lines.push(`Indexing in progress. Call search_status with searchRef=${payload.searchRef} to follow up.`);
+  }
+  if (payload.sourceStatus && payload.sourceStatus.length > 0) {
+    lines.push("source notes:");
+    for (const entry of payload.sourceStatus) {
+      lines.push(`  - ${formatSourceStatus(entry)}`);
+    }
+  }
+  return lines;
+}
+function formatSourceStatus(entry) {
+  const parts = [`${entry.source} (${entry.targetLabel})`];
+  if (entry.indexingStatus)
+    parts.push(`indexing=${entry.indexingStatus}`);
+  if (entry.codeIndexState)
+    parts.push(`codeIndex=${entry.codeIndexState}`);
+  if (entry.ignoredFilters?.length) {
+    parts.push(`ignored=${entry.ignoredFilters.join(",")}`);
+  }
+  if (entry.incompatibleFilters?.length) {
+    parts.push(`incompatible=${entry.incompatibleFilters.join(",")}`);
+  }
+  if (entry.ignoredQueryFeatures?.length) {
+    parts.push(`ignoredQuery=${entry.ignoredQueryFeatures.join(",")}`);
+  }
+  if (entry.incompatibleQueryFeatures?.length) {
+    parts.push(`incompatibleQuery=${entry.incompatibleQueryFeatures.join(",")}`);
+  }
+  if (entry.note)
+    parts.push(entry.note);
+  return parts.join(SEP3);
+}
+function quote3(value) {
+  return value.includes('"') ? `'${value}'` : `"${value}"`;
+}
+function formatDetailValue(value) {
+  if (value === null || value === undefined)
+    return "";
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  return JSON.stringify(value);
+}
+function wrapText2(text, width) {
+  const lines = [];
+  for (const paragraph of text.split(/\n/)) {
+    if (paragraph.length === 0) {
+      lines.push("");
+      continue;
+    }
+    let remaining = paragraph.trim();
+    while (remaining.length > width) {
+      let breakAt = remaining.lastIndexOf(" ", width);
+      if (breakAt <= 0)
+        breakAt = width;
+      lines.push(remaining.slice(0, breakAt).trimEnd());
+      remaining = remaining.slice(breakAt).trimStart();
+    }
+    if (remaining.length > 0)
+      lines.push(remaining);
+  }
+  return lines;
+}
 // src/shared/list-files-request.ts
 var LIMIT_MIN2 = 1;
 var LIMIT_MAX2 = 1000;
@@ -3858,6 +4768,9 @@ function parseIntCliOption(raw, name, min, max) {
   return parsed;
 }
 function formatIndexingError(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code !== "INDEXING")
     return mapped.message;
   const detail = mapped.details ?? {};
@@ -3875,6 +4788,9 @@ function formatIndexingError(mapped) {
 `);
 }
 function formatFileErrorWithFilesHint(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code === "FILE_NOT_FOUND") {
     return `${mapped.message}
   Use \`code files\` to list available paths.`;
@@ -4140,7 +5056,7 @@ grep run. --symbol-field hydrates enclosing symbol metadata (appears under each
 match in --verbose output; full payload in --json).`;
 function registerCodeGrepCommand(pkgCommand) {
   return pkgCommand.command("grep").summary("Deterministic text grep over indexed dependency source").description(PKG_GREP_DESCRIPTION).argument("[spec-or-pattern]", "Spec mode: package spec (e.g. npm:express). Repo mode (with --repo-url): the pattern.").argument("[pattern-or-prefix]", "Spec mode: the pattern. Repo mode: optional path-prefix.").argument("[path-prefix]", "Spec mode only: optional path-prefix. Ignored with --repo-url.").option("--repo-url <url>", "Repository URL addressing (requires --git-ref)").option("--git-ref <ref>", "Tag, commit, branch, or HEAD. Required with --repo-url.").option("--path <path>", "Exact file path to grep").option("--glob <glob>", "Glob scope (repeatable)", collectRepeatable, []).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable, []).option("--regex", "Interpret the pattern as RE2 regex").option("--case-sensitive", "Enable ASCII case-sensitive matching").option("-C, --context <n>", "Context lines before and after each match (0-10)").option("-B, --before-context <n>", "Context lines before each match (0-10)").option("-A, --after-context <n>", "Context lines after each match (0-10)").option("--exclude-docs", "Skip files classified as documentation").option("--exclude-tests", "Skip files classified as tests").option("--limit <n>", "Max matches to return on this page (1-1000, default 50)").option("--per-file-limit <n>", "Cap matches per file within this page (0-1000, 0 = unlimited)").option("--cursor <cursor>", "Opaque nextCursor from a previous grep result").option("--symbol-field <field>", `Repeatable; surfaces in --json and under each --verbose match. ${GREP_REPO_SYMBOL_FIELDS_NOTE}`, collectRepeatable, []).option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Render grouped output with file headers").option("--json", "Emit the JSON envelope").action(async (arg1, arg2, arg3, options) => {
-    const { createContainer: createContainer2 } = await import("./shared/chunk-4drb8s8v.js");
+    const { createContainer: createContainer2 } = await import("./shared/chunk-1gqfte6e.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -4172,9 +5088,7 @@ function buildReadFileParams(input) {
       startLine,
       endLine,
       waitTimeoutMs
-    },
-    startLineExplicit: input.startLine !== undefined,
-    endLineExplicit: input.endLine !== undefined
+    }
   };
 }
 function normaliseLine(raw, name) {
@@ -4238,7 +5152,7 @@ function formatReadFileTerminal(envelope, options) {
 function formatBinary(envelope, options, verbose) {
   const sentinel = dim("Binary file — cannot display as text.", options.useColors);
   if (verbose) {
-    return `${buildHeader2(envelope, options)}
+    return `${buildHeader5(envelope, options)}
 
 ${sentinel}
 `;
@@ -4249,7 +5163,7 @@ ${sentinel}
 function formatNoContent(envelope, options, verbose) {
   const sentinel = dim("(no content returned)", options.useColors);
   if (verbose) {
-    return `${buildHeader2(envelope, options)}
+    return `${buildHeader5(envelope, options)}
 
 ${sentinel}
 `;
@@ -4259,7 +5173,7 @@ ${sentinel}
 }
 function formatVerboseBody(envelope, options) {
   const lines = [];
-  lines.push(buildHeader2(envelope, options));
+  lines.push(buildHeader5(envelope, options));
   lines.push("");
   const content = envelope.content ?? "";
   const bodyLines = content.split(`
@@ -4275,11 +5189,15 @@ function formatVerboseBody(envelope, options) {
     const gutter = dim(String(lineNumber).padStart(gutterWidth, " "), options.useColors);
     lines.push(`${gutter}  ${bodyLines[i]}`);
   }
+  if (envelope.hint) {
+    lines.push("");
+    lines.push(dim(envelope.hint, options.useColors));
+  }
   lines.push("");
   return lines.join(`
 `);
 }
-function buildHeader2(envelope, options) {
+function buildHeader5(envelope, options) {
   const parts = [envelope.path];
   if (envelope.language)
     parts.push(envelope.language);
@@ -4522,7 +5440,7 @@ function handleDocsListError(error2, json) {
       ...mapped.details ? { details: mapped.details } : {}
     }));
   } else {
-    console.error(mapped.message);
+    console.error(formatMappedErrorForTerminal(mapped));
   }
   process.exit(1);
 }
@@ -4578,7 +5496,7 @@ function handleDocsReadError(error2, json) {
       ...mapped.details ? { details: mapped.details } : {}
     }));
   } else {
-    console.error(mapped.message);
+    console.error(formatMappedErrorForTerminal(mapped));
   }
   process.exit(1);
 }
@@ -4657,7 +5575,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-4drb8s8v.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-1gqfte6e.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -5431,6 +6349,36 @@ var TIMEOUT_MS = 5 * 60 * 1000;
 function randomPort() {
   return Math.floor(Math.random() * 2000) + 8000;
 }
+async function preflightAuthPersistence(authStorage, mcpUrl) {
+  const probeUrl = `${mcpUrl.replace(/\/+$/, "")}/__githits_storage_probe__`;
+  const probeClient = {
+    clientId: "__githits_storage_probe__",
+    clientSecret: "__githits_storage_probe__",
+    redirectUri: "http://127.0.0.1:1/callback",
+    registeredAt: new Date(0).toISOString()
+  };
+  const probeTokens = {
+    accessToken: "__githits_storage_probe__",
+    refreshToken: "__githits_storage_probe__",
+    expiresAt: new Date(0).toISOString(),
+    createdAt: new Date(0).toISOString()
+  };
+  try {
+    await authStorage.saveClient(probeUrl, probeClient);
+    await authStorage.saveTokens(probeUrl, probeTokens);
+    await authStorage.clearTokens(probeUrl);
+    await authStorage.clearClient(probeUrl);
+    return null;
+  } catch (error2) {
+    await authStorage.clearTokens(probeUrl).catch(() => {});
+    await authStorage.clearClient(probeUrl).catch(() => {});
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    return {
+      status: "failed",
+      message: `Cannot persist OAuth credentials: ${message}`
+    };
+  }
+}
 async function loginFlow(options, deps) {
   const { authService, authStorage, browserService, mcpUrl } = deps;
   if (options.port !== undefined && (Number.isNaN(options.port) || options.port < 1 || options.port > 65535)) {
@@ -5454,6 +6402,9 @@ async function loginFlow(options, deps) {
   if (!existing) {
     await authStorage.clearClient(mcpUrl);
   }
+  const persistenceError = await preflightAuthPersistence(authStorage, mcpUrl);
+  if (persistenceError)
+    return persistenceError;
   console.log("Discovering OAuth endpoints...");
   const metadata = await authService.discoverEndpoints(mcpUrl);
   let client = await authStorage.loadClient(mcpUrl);
@@ -5599,13 +6550,15 @@ You're ready to use githits with your AI assistant.`);
 var LOGIN_DESCRIPTION = `Authenticate with your GitHits account via browser.
 
 Opens your browser to complete authentication securely using OAuth.
-The CLI receives tokens stored locally and used for API requests.
+OAuth credentials are stored in the system keychain by default. If your
+machine has no usable keychain, use GITHITS_API_TOKEN or explicitly configure
+auth.storage = "file". File storage is plaintext on disk.
 
 Use --no-browser in environments without a display (CI, SSH sessions)
 to get a URL you can open on another device.`;
 function registerLoginCommand(program) {
   program.command("login").summary("Authenticate with your GitHits account").description(LOGIN_DESCRIPTION).option("--no-browser", "Print URL instead of opening browser").option("--port <port>", "Port for local callback server", parseInt).option("--force", "Re-authenticate even if already logged in").action(async (options) => {
-    const deps = await createContainer();
+    const deps = await createAuthCommandDependencies();
     await loginAction(options, deps);
   });
 }
@@ -5800,7 +6753,7 @@ function registerInitCommand(program) {
       fileSystemService,
       promptService,
       execService,
-      createLoginDeps: () => createContainer()
+      createLoginDeps: () => createAuthCommandDependencies()
     });
   });
 }
@@ -5877,10 +6830,11 @@ var LOGOUT_DESCRIPTION = `Remove stored credentials.
 
 Clears all locally stored authentication data including tokens and
 client registrations. OAuth tokens expire naturally; this
-removes the local copies from the keychain (or fallback file storage).`;
+removes local copies from the keychain, explicit file storage, and
+legacy auth file storage.`;
 function registerLogoutCommand(program) {
   program.command("logout").summary("Remove stored credentials").description(LOGOUT_DESCRIPTION).action(async () => {
-    const deps = await createContainer();
+    const deps = await createAuthCommandDependencies();
     await logoutAction(deps);
   });
 }
@@ -6066,9 +7020,10 @@ var schema3 = {
   max_matches_per_file: z4.number().optional(),
   cursor: z4.string().optional(),
   symbol_fields: z4.array(z4.enum(GREP_REPO_SYMBOL_FIELDS)).optional().describe(GREP_REPO_SYMBOL_FIELDS_NOTE),
-  wait_timeout_ms: z4.number().optional()
+  wait_timeout_ms: z4.number().optional(),
+  format: z4.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output (matches grouped by file with grep -A/-B notation for context). Pass `format: "json"` for the structured envelope. `text` is an alias for `text-v1`. Errors stay JSON-formatted in either mode for now.')
 };
-var DESCRIPTION3 = "Deterministic text grep over indexed dependency and repository source files. " + "Use this when you know the text pattern you want; use `search` for discovery. " + "Whole-target grep is the default. Narrow with `path`, `path_prefix`, `globs`, or `extensions`. " + "Matches chain directly into `code_read` via `matches[].filePath`.";
+var DESCRIPTION3 = "Deterministic text grep over indexed dependency and repository source files. " + "Use this when you know the text pattern you want; use `search` for discovery. " + "Whole-target grep is the default — narrow with `path`, `path_prefix`, `globs`, or `extensions` to keep responses small. " + 'Default response is a compact line-oriented listing (`format: "text-v1"`); pass `format: "json"` for the structured envelope. ' + "Matches chain directly into `code_read` (the `path` and `line` from each match feed straight into `start_line` / `end_line`).";
 function createGrepRepoTool(service) {
   return {
     name: "code_grep",
@@ -6124,6 +7079,9 @@ function createGrepRepoTool(service) {
           excludeTestFiles: build.params.excludeTestFiles,
           explicit: build.explicit
         });
+        if (isTextFormat(args.format)) {
+          return textResult(renderGrepRepoText(payload));
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapCodeNavigationError(error2);
@@ -6137,15 +7095,19 @@ function createGrepRepoTool(service) {
     }
   };
 }
+function isTextFormat(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/list-files.ts
 import { z as z5 } from "zod";
 var schema4 = {
   target: codeTargetSchema,
   path_prefix: z5.string().optional().describe("Literal directory prefix to filter by (e.g. `src/` or `lib/parser`). NOT a glob — `*.ts` and similar patterns won't match. Omit to list from the repository root."),
   limit: z5.number().optional().describe("Max entries to return (1–1000, default 200). Out-of-range values return an `INVALID_ARGUMENT` envelope."),
-  wait_timeout_ms: z5.number().optional().describe("Max milliseconds to wait for indexing (0–60000, default 20000). On an `INDEXING` error envelope, retry with a longer timeout or pass a version from `details.availableVersions`.")
+  wait_timeout_ms: z5.number().optional().describe("Max milliseconds to wait for indexing (0–60000, default 20000). On an `INDEXING` error envelope, retry with a longer timeout or pass a version from `details.availableVersions`."),
+  format: z5.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact paths-only listing tuned for agent context efficiency. Pass `format: "json"` for the structured envelope. `text` is an alias for `text-v1`. Errors stay JSON-formatted in either mode for now.')
 };
-var DESCRIPTION4 = "List files in an indexed dependency. Response: " + "`{total, hasMore, files: [{path, name, language, fileType, byteSize}], " + "resolution, indexedVersion}`. Address via `target.registry` + " + "`target.package_name` (package scope) or `target.repo_url` + " + "`target.git_ref` (repo scope), mutually exclusive. `path_prefix` " + "is a literal directory prefix — it does NOT accept globs " + "(`*.ts`) or extension filters. The returned `path` values feed " + "directly into `code_read` and help scope `code_grep`. Returns an `INDEXING` " + "error envelope when the dependency is being indexed on-demand — " + "retry with a longer `wait_timeout_ms` or use a version from " + "`details.availableVersions`.";
+var DESCRIPTION4 = "List files in an indexed dependency. Default response is a compact " + 'paths-only listing (`format: "text-v1"`); pass `format: "json"` ' + "for the structured envelope `{total, hasMore, files: [{path, name, " + "language, fileType, byteSize}], resolution, indexedVersion}`. " + "Address via `target.registry` + `target.package_name` (package " + "scope) or `target.repo_url` + `target.git_ref` (repo scope), " + "mutually exclusive. `path_prefix` is a literal directory prefix — " + "it does NOT accept globs (`*.ts`) or extension filters. The " + "returned paths feed directly into `code_read` and help scope " + "`code_grep`. Returns an `INDEXING` error envelope when the " + "dependency is being indexed on-demand — retry with a longer " + "`wait_timeout_ms` or use a version from `details.availableVersions`.";
 function createListFilesTool(service) {
   return {
     name: "code_files",
@@ -6174,6 +7136,9 @@ function createListFilesTool(service) {
           pathPrefix: build.params.pathPrefix,
           limit: build.params.limit
         });
+        if (isTextFormat2(args.format)) {
+          return textResult(renderListFilesText(payload));
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapCodeNavigationError(error2);
@@ -6187,6 +7152,9 @@ function createListFilesTool(service) {
     }
   };
 }
+function isTextFormat2(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/list-package-docs.ts
 import { z as z6 } from "zod";
 var schema5 = {
@@ -6675,7 +7643,7 @@ var schema9 = {
   min_severity: z10.string().optional().describe("Only return advisories at or above this severity (`low`, `medium`, `high`, `critical`; uppercase tolerated). Omit to see all, including null-severity advisories."),
   include_withdrawn: z10.boolean().optional().describe("Include retracted advisories (default: false).")
 };
-var DESCRIPTION9 = "Check known vulnerabilities for a package on npm, PyPI, Hex, or " + "Crates (other registries are not yet supported for vulnerability " + "data). Returns a count summary, each advisory with OSV ID, " + "severity, affected ranges and fix versions, plus suggested " + "upgrade paths. Malicious-package advisories surface in a separate " + "bucket. Pass `version` to inspect a specific release; otherwise " + "the latest is checked. Use `min_severity` to filter to a threshold " + "(`low`, `medium`, `high`, `critical`) and `include_withdrawn` to " + "also see retracted advisories.";
+var DESCRIPTION9 = "Check known vulnerabilities for a package on npm, PyPI, Hex, or " + "Crates (other registries are not yet supported for vulnerability " + "data). Returns a count summary, each advisory with OSV ID, " + "severity, affected ranges, and fix versions. Malicious-package advisories surface in a separate " + "bucket. Pass `version` to inspect a specific release; otherwise " + "the latest is checked. Use `min_severity` to filter to a threshold " + "(`low`, `medium`, `high`, `critical`) and `include_withdrawn` to " + "also see retracted advisories.";
 function createPackageVulnerabilitiesTool(service) {
   return {
     name: "pkg_vulns",
@@ -6718,14 +7686,34 @@ function createPackageVulnerabilitiesTool(service) {
 }
 // src/tools/read-file.ts
 import { z as z11 } from "zod";
+var MCP_READ_MAX_SPAN = 150;
 var schema10 = {
   target: codeTargetSchema,
   path: z11.string().describe("Path to the file. Package addressing: package-relative. Repo addressing: repo-relative. This is the same `path` key that `code_files` emits for each entry, so chaining needs no renaming."),
-  start_line: z11.number().optional().describe("Starting line (1-indexed). Omit for the full file from line 1."),
-  end_line: z11.number().optional().describe("Ending line (inclusive). Omit for end of file. Must be ≥ `start_line` when both are set."),
+  start_line: z11.number().optional().describe(`Starting line (1-indexed). Omit to start at line 1. The MCP surface caps any single read at ${MCP_READ_MAX_SPAN} lines — pick a focused window from your prior \`search\` / \`code_grep\` hit.`),
+  end_line: z11.number().optional().describe(`Ending line (inclusive). Must be ≥ \`start_line\` when both are set. Omitting it implies \`start_line + ${MCP_READ_MAX_SPAN - 1}\` because the MCP surface caps each read at ${MCP_READ_MAX_SPAN} lines.`),
   wait_timeout_ms: z11.number().optional().describe("Max milliseconds to wait for indexing (0–60000, default 20000). On an `INDEXING` error envelope, retry with a longer timeout or pass a version from `details.availableVersions`.")
 };
-var DESCRIPTION10 = "Read a file from an indexed dependency. Default returns the full " + "file; use `start_line` / `end_line` for a bounded range. Response: " + "`{path, language, totalLines, startLine, endLine, content, " + "isBinary}`. Binary files set `isBinary: true` and omit `content` — " + "agents branch on the flag rather than checking null. Pass the same " + "`path` emitted by `code_files`. Address via " + "`target.registry` + `target.package_name` (package scope) or " + "`target.repo_url` + `target.git_ref` (repo scope), mutually " + "exclusive. On `INDEXING` retry with a longer `wait_timeout_ms`. " + "When the path doesn't resolve the response is a `NOT_FOUND` (or " + "`FILE_NOT_FOUND`) error — call `code_files` to discover the " + "actual paths.";
+var DESCRIPTION10 = "Read a file from an indexed dependency. **MCP cap: " + `${MCP_READ_MAX_SPAN} lines per call** — broader requests (or no ` + `range) silently truncate to the first ${MCP_READ_MAX_SPAN} lines ` + "from your start, with a `hint` describing what was returned vs. " + "requested. Pick a focused window from a `search` / `code_grep` " + "match. Response: `{path, language, totalLines, startLine, endLine, " + "content, isBinary, hint?}`. Binary files set `isBinary: true` and " + "omit `content`. Pass the same `path` emitted by `code_files`. " + "Address via `target.registry` + `target.package_name` (package " + "scope) or `target.repo_url` + `target.git_ref` (repo scope), " + "mutually exclusive. On `INDEXING` retry with a longer " + "`wait_timeout_ms`. On `NOT_FOUND` / `FILE_NOT_FOUND` call " + "`code_files` to discover the actual path.";
+function deriveBoundedRange(startLine, endLine) {
+  const start = startLine ?? 1;
+  if (endLine === undefined) {
+    return {
+      startLine: start,
+      endLine: start + MCP_READ_MAX_SPAN - 1,
+      capped: true
+    };
+  }
+  const span = endLine - start + 1;
+  if (span > MCP_READ_MAX_SPAN) {
+    return {
+      startLine: start,
+      endLine: start + MCP_READ_MAX_SPAN - 1,
+      capped: true
+    };
+  }
+  return { startLine: start, endLine, capped: false };
+}
 function createReadFileTool(service) {
   return {
     name: "code_read",
@@ -6737,11 +7725,12 @@ function createReadFileTool(service) {
       if ("content" in target)
         return target;
       try {
+        const bounded = deriveBoundedRange(args.start_line, args.end_line);
         const build = buildReadFileParams({
           target,
           filePath: args.path,
-          startLine: args.start_line,
-          endLine: args.end_line,
+          startLine: bounded.startLine,
+          endLine: bounded.endLine,
           waitTimeoutMs: args.wait_timeout_ms
         });
         const result = await service.readFile(build.params);
@@ -6752,6 +7741,9 @@ function createReadFileTool(service) {
           gitRef: target.gitRef,
           requestedFilePath: build.params.filePath
         });
+        if (shouldEmitCappedHint(bounded, payload)) {
+          payload.hint = buildCappedHint(payload, args.start_line, args.end_line);
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapCodeNavigationError(error2);
@@ -6765,6 +7757,33 @@ function createReadFileTool(service) {
     }
   };
 }
+function shouldEmitCappedHint(bounded, payload) {
+  if (!bounded.capped)
+    return false;
+  if (payload.isBinary)
+    return false;
+  if (payload.endLine === undefined)
+    return false;
+  if (payload.totalLines === undefined)
+    return false;
+  return payload.endLine < payload.totalLines;
+}
+function buildCappedHint(payload, originalStart, originalEnd) {
+  const requested = describeRequest(originalStart, originalEnd);
+  return `Returned lines ${payload.startLine}-${payload.endLine}/${payload.totalLines} ` + `(MCP cap: ${MCP_READ_MAX_SPAN} lines per call; you requested ${requested}). ` + `Pick a focused start_line/end_line window — typical 80-150 lines around a search/code_grep match. ` + `Each retry also costs context, so aim for one well-sized read.`;
+}
+function describeRequest(originalStart, originalEnd) {
+  if (originalStart === undefined && originalEnd === undefined) {
+    return "no range";
+  }
+  if (originalEnd === undefined) {
+    return `start_line=${originalStart}, no end_line`;
+  }
+  if (originalStart === undefined) {
+    return `end_line=${originalEnd}, no start_line`;
+  }
+  return `lines ${originalStart}-${originalEnd}`;
+}
 // src/tools/read-package-doc.ts
 import { z as z12 } from "zod";
 var schema11 = {
@@ -6851,9 +7870,10 @@ var schema12 = {
   name: z13.string().optional(),
   language: z13.string().optional(),
   allow_partial_results: z13.boolean().optional().describe("Default false waits for all sources; if the wait window expires, returns only searchRef/progress. When true, includes hits from sources that finished so far and still returns searchRef for continuation. Partial payloads support normal pagination via nextOffset."),
-  limit: z13.coerce.number().int().min(1).max(100).optional(),
+  limit: z13.coerce.number().int().min(1).max(100).optional().describe("Maximum results to return (default 10, max 100)."),
   offset: z13.coerce.number().int().min(0).optional(),
-  wait_timeout_ms: z13.coerce.number().int().min(0).max(60000).optional()
+  wait_timeout_ms: z13.coerce.number().int().min(0).max(60000).optional(),
+  format: z13.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output tuned for agent context efficiency. Pass `format: "json"` for the structured envelope (programmatic consumers, parity testing). `text` is an alias for `text-v1`. The text format is a public, snapshot-tested contract.')
 };
 var DESCRIPTION12 = "Search indexed dependency and repository code, docs, and explicit symbols. " + "Provide either `target` for one target or `targets` for many; omit `sources` to use backend AUTO. " + "The query field uses GitHits discovery syntax (AND/OR/parens/qualifiers; see the parameter description). " + "Structured parameters combine with that query using AND semantics. " + "Results are complete by default — if indexing is still running, the response carries a `searchRef` and no hits; pass it to `search_status` to follow up. " + "Set `allow_partial_results: true` to opt into hits from sources that finished while others continue indexing. " + "Each hit's `type` tells you the follow-up tool: `documentation_page` and `repository_doc` → `docs_read` with `locator.pageId`; `repository_code` and `repository_symbol` → `code_read` with `locator.filePath` (and `locator.startLine`/`endLine` when present).";
 function createSearchTool(service) {
@@ -6891,9 +7911,16 @@ function createSearchTool(service) {
         });
         const outcome = await service.search(built.params);
         const payload = buildUnifiedSearchSuccessPayload(built.params, built.rawQuery, built.compiledQuery, outcome);
+        if (isTextFormat3(args.format)) {
+          return textResult(renderUnifiedSearchSuccess(payload));
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
-        return errorResult(JSON.stringify(buildUnifiedSearchErrorPayload(error2)));
+        const payload = buildUnifiedSearchErrorPayload(error2);
+        if (isTextFormat3(args.format)) {
+          return errorResult(renderUnifiedSearchError(payload));
+        }
+        return errorResult(JSON.stringify(payload));
       }
     }
   };
@@ -6901,6 +7928,9 @@ function createSearchTool(service) {
 function isResolvedCodeTarget(target) {
   return !("content" in target);
 }
+function isTextFormat3(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/search-language.ts
 import { z as z14 } from "zod";
 var schema13 = {
@@ -6945,60 +7975,46 @@ function createSearchStatusTool(service) {
   };
 }
 // src/commands/mcp-instructions.ts
-var CORE_BLOCK = `GitHits surfaces verified, canonical code examples from global open source. Use it when you're stuck, the user is frustrated by repeated failed attempts, you need up-to-date API usage, or the user mentions GitHits.
+var CORE_BLOCK = `GitHits provides verified, canonical code examples from global open source. Use it when you're stuck, repeated attempts failed, you need up-to-date API usage, the question is comparative across OSS projects (e.g. "how does X vs Y handle Z"), the answer requires reading how a real codebase implements a feature, or the user mentions GitHits.
 
-Workflow: call \`get_example\` with one focused question, optionally passing \`language\` when the desired language is known; call \`search_language\` first only if you need to force a language and the exact name is uncertain. Send \`feedback\` on the returned solution_id so quality improves. Each search addresses a single issue; reuse context from prior results before re-searching.`;
-var PACKAGE_TOOLS_PREAMBLE = `Package tools work with third-party dependency source plus registry metadata. Use them when a stack trace points into a dependency, you need to verify how a library actually works, or you're evaluating whether to add or upgrade a package.
+Example workflow: call \`get_example\` with one focused question; pass \`language\` only when you know the exact language name, otherwise call \`search_language\` first. Send \`feedback\` on the returned solution_id. Reuse prior results before searching again.`;
+var PACKAGE_TOOLS_PREAMBLE = `Indexed package/source tools inspect third-party dependency source, docs, and registry metadata. Use them when a stack trace points into a dependency, you need to verify how a library works, or you're evaluating whether to add or upgrade a package.
 
 Package spec: \`registry:name[@version]\`.`;
 var PKG_INFO_BULLET = "- `pkg_info` — instant package overview: latest version, license, downloads, quickstart, and active advisory count.";
-var DOCS_LIST_BULLET = "- `docs_list` — browse mixed package documentation pages from hosted docs and repository-backed docs. Each entry includes a stable pageId, source kind, source URL, and for repo docs exact file follow-up metadata.";
+var DOCS_LIST_BULLET = "- `docs_list` — browse hosted and repository-backed package docs. Entries include stable pageIds, source URLs, and repo-file follow-up metadata when available.";
 var DOCS_READ_BULLET = "- `docs_read` — read a documentation page by pageId. Works for both hosted docs and repo-backed docs.";
-var PKG_VULNS_BULLET = "- `pkg_vulns` — known CVE / OSV advisories for npm, PyPI, Hex, or Crates packages (optionally pinned to `@version`). Malicious-package advisories surface in a disjoint `malware` bucket; filter with `min_severity` or include retracted advisories with `include_withdrawn`.";
-var PKG_DEPS_BULLET = "- `pkg_deps` — direct runtime deps plus, when the backend has them, dev / peer / optional / feature groups. Pass `lifecycle` to filter groups server-side, `include_transitive` for the full graph, and `include_importers` when you also need per-package provenance. Supports npm, PyPI, Hex, Crates, vcpkg, and Zig.";
-var PKG_CHANGELOG_BULLET = "- `pkg_changelog` — release notes for a package or GitHub repo, newest-first. Default latest mode returns the 10 most recent entries with full markdown bodies; `from_version` switches to range mode between two versions. Addressable via `registry` + `package_name` or `repo_url`. Set `include_bodies: false` for a version / date / URL timeline when bodies aren't needed.";
-var SEARCH_BULLET = "- `search` — unified search across indexed dependency code, docs, and explicit symbols. Structured fields are the primary UX; omit `sources` for AUTO. Returns only trustworthy complete results by default; opt into partial hits with `allow_partial_results: true`. If indexing is still in progress, the response carries a `searchRef`.";
-var SEARCH_STATUS_BULLET = "- `search_status` — follow up a prior unified search by `searchRef`. Use it after `search` returns incomplete state to check progress, fetch partial hits when the original request used `allow_partial_results: true`, or fetch final results.";
-var CODE_FILES_BULLET = "- `code_files` — discover what files a dependency ships. Use `path_prefix` to scope to a subdirectory; the response includes each file's language, type, and byte size. Returned `path` values feed directly into `code_read` and help scope `code_grep`.";
-var CODE_READ_BULLET = "- `code_read` — fetch a file's contents from a dependency. Pass the same `path` emitted by `code_files`. Default returns the full file; pass `start_line` / `end_line` for a bounded range. Binary files set `isBinary: true` and omit `content` — branch on the flag. A `FILE_NOT_FOUND` (or `NOT_FOUND`) response is the signal to call `code_files` for the actual path.";
-var CODE_GREP_BULLET = "- `code_grep` — deterministic text grep over indexed source files. Use it when you know the exact text or regex to match; use `search` for discovery. Whole-target grep is the default; narrow with `path`, `path_prefix`, `globs`, or `extensions`. Returned `matches[].filePath` feeds directly into `code_read`.";
-var SEARCH_VS_SYMBOLS_TIP = 'Prefer `get_example` for canonical example retrieval; prefer unified `search` for indexed dependency and repository discovery; use `sources:["symbol"]` when you want symbol-shaped results. Use `code_grep` for deterministic text matching and `code_read` for full-file inspection.';
-function isPackageToolsCapabilityOpen(deps) {
-  return deps.codeNavigationCliOverrideEnabled || deps.codeNavigationCapability === "enabled" || deps.codeNavigationCapability === "unknown" && deps.envApiToken !== undefined;
-}
-function buildMcpInstructions(deps) {
+var PKG_VULNS_BULLET = "- `pkg_vulns` — known CVE / OSV advisories for npm, PyPI, Hex, or Crates packages, optionally pinned to `@version`. Filter with `min_severity`; include retracted advisories with `include_withdrawn`.";
+var PKG_DEPS_BULLET = "- `pkg_deps` — direct runtime deps plus lifecycle/feature groups when available. Use `lifecycle` to filter groups, `include_transitive` for the full graph, and `include_importers` for provenance. Supports npm, PyPI, Hex, Crates, vcpkg, and Zig.";
+var PKG_CHANGELOG_BULLET = "- `pkg_changelog` — release notes for a package or GitHub repo, newest-first. Default latest mode returns recent entries with markdown bodies; `from_version` switches to range mode. Set `include_bodies: false` for a compact timeline.";
+var SEARCH_BULLET = '- `search` — unified search across indexed dependency code, docs, and symbols. Omit `sources` for AUTO. Default output is compact `text-v1`; pass `format: "json"` for locators, highlights, and source status. Complete by default; opt into partial hits with `allow_partial_results: true`. Incomplete responses carry a `searchRef`.';
+var SEARCH_STATUS_BULLET = "- `search_status` — follow up a prior `search` by `searchRef` to check progress, fetch partial hits, or fetch final results.";
+var CODE_FILES_BULLET = '- `code_files` — list files in an indexed dependency. Use `path_prefix` to scope to a directory. Returned paths feed into `code_read` and help scope `code_grep`; pass `format: "json"` for language/type/size metadata.';
+var CODE_READ_BULLET = "- `code_read` — read a dependency file by `path`. **MCP cap: 150 lines per call**; choose focused `start_line` / `end_line` windows from `search` or `code_grep`. Binary files set `isBinary: true` and omit `content`. On `FILE_NOT_FOUND` / `NOT_FOUND`, call `code_files` for the actual path.";
+var CODE_GREP_BULLET = "- `code_grep` — deterministic text or regex grep over indexed source. Use it when you know the pattern; use `search` for discovery. Narrow with `path`, `path_prefix`, `globs`, or `extensions`. Each match's `path:line` chains into `code_read`.";
+var SEARCH_VS_SYMBOLS_TIP = 'Prefer `get_example` for canonical example retrieval; prefer unified `search` for indexed dependency and repository discovery; use `sources:["symbol"]` when you want symbol-shaped results. Use `code_grep` for deterministic text matching and `code_read` for focused-window inspection of a known file.';
+var REFERENCE_FIRST_TIP = "Strategy — reference-first, content-second. Locate symbols and lines with `search` / `code_grep` first, then read only the needed window with `code_read` using explicit `start_line` / `end_line` values, typically 80-150 lines around the match. The MCP `code_read` surface caps each call at 150 lines.";
+var MULTI_TURN_TIP = '**Delegate multi-call work to a sub-agent.** Code-navigation work (`search`, `code_grep`, `code_read`, `code_files`) often takes 3-10 calls. For cross-project comparisons, codebase mapping, pattern surveys, or "how does X actually work" investigations, spawn a sub-task/sub-agent and ask for a compact synthesis. Do it inline only when the raw snippet belongs in the main conversation.';
+function buildMcpInstructions(_deps) {
   const sections = [CORE_BLOCK];
-  if (!isPackageToolsCapabilityOpen(deps)) {
-    return sections.join(`
-
-`);
-  }
   const bullets = [];
-  if (deps.packageIntelligenceService) {
-    bullets.push(DOCS_LIST_BULLET);
-    bullets.push(DOCS_READ_BULLET);
-    bullets.push(PKG_INFO_BULLET);
-    bullets.push(PKG_VULNS_BULLET);
-    bullets.push(PKG_DEPS_BULLET);
-    bullets.push(PKG_CHANGELOG_BULLET);
-  }
-  if (deps.codeNavigationService) {
-    bullets.push(SEARCH_BULLET);
-    bullets.push(SEARCH_STATUS_BULLET);
-    bullets.push(CODE_FILES_BULLET);
-    bullets.push(CODE_READ_BULLET);
-    bullets.push(CODE_GREP_BULLET);
-  }
-  if (bullets.length === 0) {
-    return sections.join(`
-
-`);
-  }
-  const parts = [PACKAGE_TOOLS_PREAMBLE, bullets.join(`
-`)];
-  if (deps.codeNavigationService) {
-    parts.push(SEARCH_VS_SYMBOLS_TIP);
-  }
+  bullets.push(DOCS_LIST_BULLET);
+  bullets.push(DOCS_READ_BULLET);
+  bullets.push(PKG_INFO_BULLET);
+  bullets.push(PKG_VULNS_BULLET);
+  bullets.push(PKG_DEPS_BULLET);
+  bullets.push(PKG_CHANGELOG_BULLET);
+  bullets.push(SEARCH_BULLET);
+  bullets.push(SEARCH_STATUS_BULLET);
+  bullets.push(CODE_FILES_BULLET);
+  bullets.push(CODE_READ_BULLET);
+  bullets.push(CODE_GREP_BULLET);
+  const parts = [PACKAGE_TOOLS_PREAMBLE];
+  parts.push(MULTI_TURN_TIP);
+  parts.push(bullets.join(`
+`));
+  parts.push(REFERENCE_FIRST_TIP);
+  parts.push(SEARCH_VS_SYMBOLS_TIP);
   sections.push(parts.join(`
 
 `));
@@ -7014,22 +8030,17 @@ function getMcpToolDefinitions(deps) {
     eraseTool(createSearchLanguageTool(deps.githitsService)),
     eraseTool(createFeedbackTool(deps.githitsService))
   ];
-  const gateOpen = isPackageToolsCapabilityOpen(deps);
-  if (gateOpen && deps.codeNavigationService) {
-    tools.push(eraseTool(createSearchTool(deps.codeNavigationService)));
-    tools.push(eraseTool(createSearchStatusTool(deps.codeNavigationService)));
-    tools.push(eraseTool(createListFilesTool(deps.codeNavigationService)));
-    tools.push(eraseTool(createReadFileTool(deps.codeNavigationService)));
-    tools.push(eraseTool(createGrepRepoTool(deps.codeNavigationService)));
-  }
-  if (gateOpen && deps.packageIntelligenceService) {
-    tools.push(eraseTool(createListPackageDocsTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createReadPackageDocTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createPackageSummaryTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createPackageVulnerabilitiesTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createPackageDependenciesTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createPackageChangelogTool(deps.packageIntelligenceService)));
-  }
+  tools.push(eraseTool(createSearchTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createSearchStatusTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createListFilesTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createReadFileTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createGrepRepoTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createListPackageDocsTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createReadPackageDocTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createPackageSummaryTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createPackageVulnerabilitiesTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createPackageDependenciesTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createPackageChangelogTool(deps.packageIntelligenceService)));
   return tools;
 }
 function eraseTool(tool) {
@@ -7097,7 +8108,7 @@ function registerMcpCommand(program) {
 When run interactively (TTY), shows setup instructions.
 When run via stdio (non-TTY), starts the MCP server.
 
-Available tools depend on the current authentication state and enabled features.`).action(async () => {
+Authenticated tool calls require a valid GitHits token.`).action(async () => {
     if (process.stdout.isTTY && process.stdin.isTTY) {
       showMcpSetupInstructions();
       return;
@@ -7186,6 +8197,9 @@ function handlePkgChangelogCommandError(error2, json) {
   process.exit(1);
 }
 function formatChangelogTerminalError(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code !== "VERSION_NOT_FOUND")
     return mapped.message;
   const detail = mapped.details ?? {};
@@ -7309,6 +8323,9 @@ function handlePkgDepsCommandError(error2, json) {
   process.exit(1);
 }
 function formatDepsTerminalError(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code !== "VERSION_NOT_FOUND")
     return mapped.message;
   const detail = mapped.details ?? {};
@@ -7395,7 +8412,7 @@ function handlePkgInfoCommandError(error2, json) {
     }));
     process.exit(1);
   }
-  console.error(mapped.message);
+  console.error(formatMappedErrorForTerminal(mapped));
   process.exit(1);
 }
 var PKG_INFO_DESCRIPTION = `Get a package overview — latest version, license, description,
@@ -7468,6 +8485,9 @@ function handlePkgVulnsCommandError(error2, json) {
   process.exit(1);
 }
 function formatVulnsTerminalError(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code !== "VERSION_NOT_FOUND")
     return mapped.message;
   const detail = mapped.details ?? {};
@@ -7492,8 +8512,8 @@ function formatVulnsTerminalError(mapped) {
 `);
 }
 var PKG_VULNS_DESCRIPTION = `Show known vulnerabilities for a package. Lists CVE / OSV advisories
-with severity, affected version ranges, fix versions, and suggested
-upgrade paths. Malicious-package advisories are flagged prominently.
+with severity, affected version ranges, and fix versions.
+Malicious-package advisories are flagged prominently.
 
 Package spec: <registry>:<name>[@<version>]. Supported registries:
 npm, pypi, hex, crates. Omit @<version> to check the latest release.
@@ -7620,7 +8640,7 @@ function registerSearchCommand(program) {
     "fixture",
     "build",
     "vendor"
-  ])).option("--public", "Filter to public symbols when supported").option("--name <name>", "Structured name qualifier").option("--lang <language>", "Structured language qualifier").option("--allow-partial", "Include hits already available while indexing continues; a searchRef is still returned so search-status can fetch the rest").option("--limit <n>", "Max results (1-100)").option("--offset <n>", "Result offset").option("--wait <seconds>", "Max seconds to wait before returning a searchRef (0-60; default: 20)").option("--json", "Output as JSON").action(async (query, options) => {
+  ])).option("--public", "Filter to public symbols when supported").option("--name <name>", "Structured name qualifier").option("--lang <language>", "Structured language qualifier").option("--allow-partial", "Include hits already available while indexing continues; a searchRef is still returned so search-status can fetch the rest").option("--limit <n>", "Max results (1-100, default: 10)").option("--offset <n>", "Result offset").option("--wait <seconds>", "Max seconds to wait before returning a searchRef (0-60; default: 20)").option("--json", "Output as JSON").action(async (query, options) => {
     const deps = await loadContainer2();
     await searchAction(query, options, deps);
   });
@@ -7634,14 +8654,6 @@ async function registerUnifiedSearchCommands(program, options = {}) {
   if (!codeNavigationUrl) {
     return;
   }
-  const overrideEnabled = options.overrideEnabled ?? isCodeNavigationCliOverrideEnabled();
-  const registrationState = options.capability !== undefined || options.expiredStoredAuth !== undefined ? {
-    capability: options.capability ?? "unknown",
-    expiredStoredAuth: options.expiredStoredAuth ?? false
-  } : await loadStartupCodeNavigationRegistrationState();
-  if (!overrideEnabled && registrationState.capability !== "enabled" && !registrationState.expiredStoredAuth) {
-    return;
-  }
   registerSearchCommand(program);
 }
 function requireSearchService(deps) {
@@ -7651,13 +8663,9 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-4drb8s8v.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-1gqfte6e.js");
   return createContainer2();
 }
-async function loadStartupCodeNavigationRegistrationState() {
-  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-4drb8s8v.js");
-  return resolveStartupCodeNavigationRegistrationState2();
-}
 function parseTargetSpecs(specs) {
   if (!specs || specs.length === 0) {
     throw new InvalidArgumentError("Provide at least one --in target.");
@@ -7990,7 +8998,32 @@ function formatUnifiedSearchMetadata(entry, useColors) {
 }
 // src/cli.ts
 var program = new Command;
+var argv = process.argv.slice(2);
 var commandSpans = new WeakMap;
+var createUpdateCheckService = () => new NpmRegistryUpdateCheckService({
+  currentVersion: version,
+  fileSystemService: new FileSystemServiceImpl
+});
+await enforceCachedRequiredUpdateForInvocation({
+  args: argv,
+  env: process.env,
+  createService: createUpdateCheckService,
+  stderr: process.stderr,
+  exit: process.exit
+});
+var updateCheckTask = startUpdateCheckTaskForInvocation({
+  args: argv,
+  env: process.env,
+  stderrIsTTY: process.stderr.isTTY === true,
+  stdinIsTTY: process.stdin.isTTY === true,
+  stdoutIsTTY: process.stdout.isTTY === true,
+  createService: createUpdateCheckService
+});
+var requiredUpdateRefreshTask = startRequiredUpdateRefreshTaskForInvocation({
+  args: argv,
+  env: process.env,
+  createService: createUpdateCheckService
+});
 if (isTelemetryEnabled()) {
   process.once("exit", (exitCode) => {
     flushTelemetry(exitCode);
@@ -8021,25 +9054,34 @@ registerMcpCommand(program);
 registerExampleCommand(program);
 registerLanguagesCommand(program);
 registerFeedbackCommand(program);
-var argv = process.argv.slice(2);
 var registrationArgv = stripRootRegistrationOptions(argv);
-var shouldLoadGatedHelpRegistration = needsGatedHelpRegistration(registrationArgv);
-var helpRegistrationOptions = shouldLoadGatedHelpRegistration ? await loadHelpRegistrationOptions(registrationArgv) : undefined;
 if (shouldEagerLoadSearchCommands(registrationArgv)) {
-  await withTelemetrySpan("cli.register.search", () => registerUnifiedSearchCommands(program, helpRegistrationOptions));
+  await withTelemetrySpan("cli.register.search", () => registerUnifiedSearchCommands(program));
 }
 if (shouldEagerLoadGatedCommandGroup(registrationArgv, "code")) {
-  await withTelemetrySpan("cli.register.code-group", () => registerCodeCommandGroup(program, helpRegistrationOptions));
+  await withTelemetrySpan("cli.register.code-group", () => registerCodeCommandGroup(program));
 }
 if (shouldEagerLoadGatedCommandGroup(registrationArgv, "pkg")) {
-  await withTelemetrySpan("cli.register.pkg-group", () => registerPkgCommandGroup(program, helpRegistrationOptions));
+  await withTelemetrySpan("cli.register.pkg-group", () => registerPkgCommandGroup(program));
 }
 if (shouldEagerLoadGatedCommandGroup(registrationArgv, "docs")) {
-  await withTelemetrySpan("cli.register.docs-group", () => registerDocsCommandGroup(program, helpRegistrationOptions));
+  await withTelemetrySpan("cli.register.docs-group", () => registerDocsCommandGroup(program));
 }
 var authCommand = program.command("auth").summary("Manage authentication").description("Manage authentication with GitHits.");
 registerAuthStatusCommand(authCommand);
-await withTelemetrySpan("cli.parse", () => program.parseAsync());
+try {
+  await runWithUpdateCheckFlush(() => withTelemetrySpan("cli.parse", () => program.parseAsync()), updateCheckTask, { stderr: process.stderr, requiredUpdateRefreshTask });
+} catch (error2) {
+  if (isUserFacingError(error2)) {
+    console.error(`${error2.message}
+`);
+    process.exit(1);
+  }
+  throw error2;
+}
+function isUserFacingError(error2) {
+  return error2 instanceof AuthConfigError || error2 instanceof AuthStoragePolicyError;
+}
 function stripRootRegistrationOptions(args) {
   return args.filter((arg) => arg !== "--no-color");
 }
@@ -8051,34 +9093,9 @@ function shouldEagerLoadSearchCommands(args) {
   const [firstArg] = args;
   return args.length === 0 || firstArg === "search" || firstArg === "search-status" || firstArg === "--help" || firstArg === "-h" || firstArg === "help" && (!args[1] || isSearchHelpTarget(args[1]));
 }
-function isHelpInvocation(args) {
-  return args.length === 0 || args[0] === "help" || args.includes("--help") || args.includes("-h");
-}
-function needsGatedHelpRegistration(args) {
-  if (!isHelpInvocation(args)) {
-    return false;
-  }
-  const [firstArg, secondArg] = args;
-  if (firstArg === "help") {
-    return isSearchHelpTarget(secondArg) || secondArg === "code" || secondArg === "pkg" || secondArg === "docs";
-  }
-  return isSearchHelpTarget(firstArg) || firstArg === "code" || firstArg === "pkg" || firstArg === "docs";
-}
 function isSearchHelpTarget(value) {
   return value === "search" || value === "search-status";
 }
-async function loadHelpRegistrationOptions(args) {
-  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-4drb8s8v.js");
-  const registrationState = await resolveStartupCodeNavigationRegistrationState2();
-  return {
-    capability: registrationState.capability,
-    expiredStoredAuth: shouldUseExpiredStoredAuthFallbackForHelp(args) ? registrationState.expiredStoredAuth : false
-  };
-}
-function shouldUseExpiredStoredAuthFallbackForHelp(args) {
-  const [firstArg, secondArg] = args;
-  return firstArg === "search" || firstArg === "search-status" || firstArg === "code" || firstArg === "pkg" || firstArg === "docs" || firstArg === "help" && (isSearchHelpTarget(secondArg) || secondArg === "code" || secondArg === "pkg" || secondArg === "docs");
-}
 function getTelemetryCommandName(command) {
   const names = [];
   let current = command;