deepseek-web-retrieval 0.5.1 → 0.7.0

package/src/core/descriptions.ts

@@ -16,7 +16,7 @@ export const SEARCH_RANKED_FILTERED =
 export const SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error.";
 
 export const SEARCH_QUERY_OPERATORS =
-  "Use site:/-site: operators in the query to include or exclude domains; the full query must stay within 128 characters.";
+  "Use site:/-site: operators in the query to include or exclude domains, and after:/before: with a year or date (e.g. after:2025-06-01) to filter by publish time; the full query must stay within 128 characters.";
 
 /**
  * The full tool descriptions, composed from the fact fragments. Every host
@@ -38,6 +38,10 @@ export const FETCH_TOOL_DESCRIPTION =
 
 /** Parameter descriptions shared by every adapter's input schema for the two tools. */
 export const SEARCH_QUERY_PARAMETER =
-  "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:).";
+  "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:, after:, before:).";
+
+export const SEARCH_ORI_QUESTION_PARAMETER =
+  "The user's original question or task that triggered this search, in the user's own words rather than a " +
+  "reformulated query. Optional; 1-128 characters, and longer values are truncated.";
 
 export const FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.";

package/src/core/env.ts

@@ -1,4 +1,5 @@
-import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "./constants";
+import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, SEARCH_LOCALIZATION_ENV } from "./constants";
+import { normalizeDomain } from "./domains";
 import { resolvePluginOptions } from "./options";
 import type { PluginOptions, ResolvedOptions } from "./types";
 
@@ -21,6 +22,7 @@ const NUMBER_ENV = {
 
 const TEXT_ENV = {
   language: "DEEPSEEK_SEARCH_LANGUAGE",
+  searchLocalization: SEARCH_LOCALIZATION_ENV,
 } as const;
 
 const DOMAINS_ENV = {
@@ -38,51 +40,92 @@ const FALSE_ONLY_ENV = {
   fetchEnabled: ENABLE_FETCH_ENV,
 } as const;
 
+/**
+ * Every option's `DEEPSEEK_*` variable name, in map order — the names a host that
+ * isolates its children from the parent environment (Codex) must forward for
+ * shell-set options to reach the server. `DEEPSEEK_API_KEY` is deliberately
+ * absent: it is not an option variable, and installers compose it separately.
+ */
+export const OPTION_ENV_VARS: readonly string[] = [
+  ...Object.values(NUMBER_ENV),
+  ...Object.values(TEXT_ENV),
+  ...Object.values(DOMAINS_ENV),
+  ...Object.values(FALSE_ONLY_ENV),
+];
+
 /**
  * Maps `DEEPSEEK_*` environment variables onto the shared plugin option keys and
  * resolves them through the shared pipeline, so defaults and clamping stay
  * identical across every adapter. Invalid values are dropped and the shared
- * default applies.
+ * default applies; `envOptionsReport` is where those drops become visible.
+ * `fileOptions` (the shared config file) layer beneath the environment: for
+ * the same key the environment wins.
  */
-export function resolveEnvOptions(env: Env = process.env): ResolvedOptions {
-  return resolvePluginOptions(pluginOptionsFromEnv(env));
+export function resolveEnvOptions(env: Env = process.env, fileOptions?: PluginOptions): ResolvedOptions {
+  return resolvePluginOptions({ ...fileOptions, ...pluginOptionsFromEnv(env) });
 }
 
-export function pluginOptionsFromEnv(env: Env): PluginOptions {
-  const options: Record<string, unknown> = {};
+/**
+ * What reading the `DEEPSEEK_*` environment produced, plus the problems as
+ * structured data. Startup paths stay silent (they use pluginOptionsFromEnv);
+ * surfaces whose job is visibility — the config command — replay these
+ * warnings through their own channel.
+ */
+export interface EnvOptionsReport {
+  readonly options: PluginOptions;
+  /** One entry per set-but-unusable `DEEPSEEK_*` variable: unknown names and values that had to be dropped. */
+  readonly warnings: readonly string[];
+}
 
-  putNumber(options, "count", env);
-  putNumber(options, "maxResults", env);
-  putNumber(options, "minRerank", env);
-  putNumber(options, "minAuthority", env);
-  putFalseOnly(options, "allowUnknownAuthority", env);
-  putDomains(options, "blockedDomains", env);
-  putDomains(options, "includeDomains", env);
+/** The options layer of the environment, with every drop reported instead of silent. */
+export function envOptionsReport(env: Env = process.env): EnvOptionsReport {
+  const options: Record<string, unknown> = {};
+  const warnings: string[] = [];
+
+  putNumber(options, "count", env, warnings);
+  putNumber(options, "maxResults", env, warnings);
+  putNumber(options, "minRerank", env, warnings);
+  putNumber(options, "minAuthority", env, warnings);
+  putFalseOnly(options, "allowUnknownAuthority", env, warnings);
+  putDomains(options, "blockedDomains", env, warnings);
+  putDomains(options, "includeDomains", env, warnings);
   putText(options, "language", env);
-  putNumber(options, "maxSummaryChars", env);
-  putNumber(options, "searchTimeoutMs", env);
-
-  putNumber(options, "fetchMaxChars", env);
-  putDomains(options, "fetchAllowedDomains", env);
-  putDomains(options, "fetchBlockedDomains", env);
-  putNumber(options, "fetchTimeoutMs", env);
-  putFalseOnly(options, "fetchBlockPrivateHosts", env);
-  putFalseOnly(options, "searchEnabled", env);
-  putFalseOnly(options, "fetchEnabled", env);
-
-  putNumber(options, "maxRetries", env);
-  putNumber(options, "retryBaseDelayMs", env);
+  putText(options, "searchLocalization", env);
+  putNumber(options, "maxSummaryChars", env, warnings);
+  putNumber(options, "searchTimeoutMs", env, warnings);
+
+  putNumber(options, "fetchMaxChars", env, warnings);
+  putDomains(options, "fetchAllowedDomains", env, warnings);
+  putDomains(options, "fetchBlockedDomains", env, warnings);
+  putNumber(options, "fetchTimeoutMs", env, warnings);
+  putFalseOnly(options, "fetchBlockPrivateHosts", env, warnings);
+  putFalseOnly(options, "searchEnabled", env, warnings);
+  putFalseOnly(options, "fetchEnabled", env, warnings);
+
+  putNumber(options, "maxRetries", env, warnings);
+  putNumber(options, "retryBaseDelayMs", env, warnings);
+
+  const known = new Set(OPTION_ENV_VARS);
+  for (const key of Object.keys(env)) {
+    if (!key.startsWith("DEEPSEEK_") || key === API_KEY_ENV || known.has(key)) continue;
+    if (!(env[key] ?? "").trim()) continue;
+    warnings.push(`unknown DEEPSEEK_* variable ${key} — ignored`);
+  }
+  return { options, warnings };
+}
 
-  return options;
+export function pluginOptionsFromEnv(env: Env): PluginOptions {
+  return envOptionsReport(env).options;
 }
 
-function putNumber(target: Record<string, unknown>, key: keyof typeof NUMBER_ENV, env: Env): void {
+function putNumber(target: Record<string, unknown>, key: keyof typeof NUMBER_ENV, env: Env, warnings: string[]): void {
   const value = env[NUMBER_ENV[key]];
   if (value === undefined) return;
   const trimmed = value.trim();
   if (!trimmed) return;
   const parsed = Number(trimmed);
   if (Number.isFinite(parsed)) target[key] = parsed;
+  else warnings.push(`${NUMBER_ENV[key]} is not a number ("${trimmed}") — ignored`);
 }
 
 function putText(target: Record<string, unknown>, key: keyof typeof TEXT_ENV, env: Env): void {
@@ -92,18 +135,42 @@ function putText(target: Record<string, unknown>, key: keyof typeof TEXT_ENV, en
   if (trimmed) target[key] = trimmed;
 }
 
-function putFalseOnly(target: Record<string, unknown>, key: keyof typeof FALSE_ONLY_ENV, env: Env): void {
-  if (isFalseValue(env[FALSE_ONLY_ENV[key]])) target[key] = false;
+function putFalseOnly(
+  target: Record<string, unknown>,
+  key: keyof typeof FALSE_ONLY_ENV,
+  env: Env,
+  warnings: string[],
+): void {
+  const name = FALSE_ONLY_ENV[key];
+  const value = env[name];
+  if (value === undefined || !value.trim()) return;
+  if (isFalseValue(value)) {
+    target[key] = false;
+    return;
+  }
+  warnings.push(`${name}="${value.trim()}" changes nothing — only false/0/no/off turns the switch off`);
 }
 
-function putDomains(target: Record<string, unknown>, key: keyof typeof DOMAINS_ENV, env: Env): void {
-  const value = env[DOMAINS_ENV[key]];
+function putDomains(
+  target: Record<string, unknown>,
+  key: keyof typeof DOMAINS_ENV,
+  env: Env,
+  warnings: string[],
+): void {
+  const name = DOMAINS_ENV[key];
+  const value = env[name];
   if (value === undefined || !value.trim()) return;
   const domains = value
     .split(",")
     .map((domain) => domain.trim())
     .filter((domain) => domain.length > 0);
+  for (const domain of domains) {
+    if (normalizeDomain(domain) === undefined) {
+      warnings.push(`${name} entry "${domain}" is not a domain — ignored`);
+    }
+  }
   if (domains.length > 0) target[key] = domains;
+  else warnings.push(`${name} contains no domains — ignored`);
 }
 
 function isFalseValue(value: string | undefined): boolean {

package/src/core/format.ts

@@ -95,7 +95,8 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
   return results
     .map((result, index) => {
       const title = result.title?.trim() || result.url;
-      const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})`];
+      const marker = formatQualityMarker(result);
+      const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})${marker ? ` ${marker}` : ""}`];
       if (result.content) {
         lines.push(`   ${result.content.replaceAll("\n", " ")}`);
       }
@@ -107,6 +108,20 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
     .join("\n\n");
 }
 
+/**
+ * Renders the quality fields DeepSeek reports as one bracketed token on the
+ * result's heading line; the text channel is the only one every host delivers
+ * to the model. Authority -1 means unknown and stays in the structured shape
+ * only, so it never wastes text.
+ */
+export function formatQualityMarker(result: SearchResult): string {
+  const parts: string[] = [];
+  if (result.rerankScore !== undefined) parts.push(`rerank ${result.rerankScore}`);
+  if (result.authority !== undefined && result.authority >= 0) parts.push(`authority ${result.authority}`);
+  if (result.siteName) parts.push(result.siteName);
+  return parts.length > 0 ? `[${parts.join(" · ")}]` : "";
+}
+
 /**
  * Renders one search result as the structured mirror of its text form; hosts
  * that read structuredContent (every JSON-replacing client excepted) get this
@@ -118,6 +133,9 @@ export function toStructuredResult(result: SearchResult) {
     ...(result.title ? { title: result.title } : {}),
     ...(result.content ? { content: result.content } : {}),
     ...(result.published !== undefined ? { published: result.published } : {}),
+    ...(result.rerankScore !== undefined ? { rerankScore: result.rerankScore } : {}),
+    ...(result.authority !== undefined ? { authority: result.authority } : {}),
+    ...(result.siteName ? { siteName: result.siteName } : {}),
   };
 }
 

package/src/core/options.ts

@@ -1,3 +1,4 @@
+import { isIP } from "node:net";
 import {
   DEFAULT_API_KEY_SOURCE,
   DEFAULT_FETCH_MAX_CHARS,
@@ -35,15 +36,21 @@ export function resolvePluginOptions(input?: PluginOptions): ResolvedOptions {
 }
 
 export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
+  const count = clampInt(input?.count, DEFAULT_SEARCH_COUNT, 1, 50);
   return {
-    count: clampInt(input?.count, DEFAULT_SEARCH_COUNT, 1, 50),
-    maxResults: clampInt(input?.maxResults, DEFAULT_MAX_RESULTS, 0, 50),
+    count,
+    // Constraint: maxResults follows count only when the user left it alone —
+    // an explicit maxResults still caps as before. count never follows
+    // maxResults: fetching more than the cap returns wastes nothing visible,
+    // while returning fewer than were fetched silently discards results.
+    maxResults: clampInt(input?.maxResults, Number.isFinite(input?.count) ? count : DEFAULT_MAX_RESULTS, 0, 50),
     minRerank: finiteNumber(input?.minRerank, DEFAULT_MIN_RERANK),
     minAuthority: finiteNumber(input?.minAuthority, DEFAULT_MIN_AUTHORITY),
     allowUnknownAuthority: input?.allowUnknownAuthority !== false,
     blockedDomains: normalizeDomains(input?.blockedDomains),
     includeDomains: normalizeDomains(input?.includeDomains),
     language: optionalText(input?.language),
+    localization: localizationValue(input?.searchLocalization),
     maxSummaryChars: clampInt(input?.maxSummaryChars, DEFAULT_MAX_SUMMARY_CHARS, 0, 1_000_000),
     timeoutMs: clampInt(input?.searchTimeoutMs, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
     enabled: input?.searchEnabled !== false,
@@ -93,6 +100,19 @@ function optionalText(value: unknown): string | undefined {
   return trimmed ? trimmed : undefined;
 }
 
+/**
+ * Constraint: only a valid IPv4 dotted-quad (four 0-255 octets) or IPv6
+ * address (including "::" compression) survives; anything else drops to
+ * undefined so the request omits `localization` entirely. This is the
+ * enforcement point no matter which config channel delivered the value.
+ */
+function localizationValue(value: unknown): string | undefined {
+  const text = optionalText(value);
+  // isIP is the platform's strict parser; its one lax spot is IPv6 zone IDs
+  // ("%eth0"), which name a local link, not a geolocation — reject those.
+  return text !== undefined && !text.includes("%") && isIP(text) !== 0 ? text : undefined;
+}
+
 function finiteNumber(value: unknown, fallback: number): number {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }

package/src/core/search.ts

@@ -67,11 +67,17 @@ export function processResults(raw: readonly DeepSeekSearchResult[], options: Se
     const content = truncate(optionalText(item.summary) ?? optionalText(item.snippet) ?? "", options.maxSummaryChars);
     const published = parsePublished(item.date);
     const title = optionalText(item.title);
+    const rerankScore = typeof rerank === "number" && Number.isFinite(rerank) ? rerank : undefined;
+    const authorityScore = typeof authority === "number" && Number.isFinite(authority) ? authority : undefined;
+    const siteName = optionalText(item.site_name);
     results.push({
       url,
       ...(title ? { title } : {}),
       ...(content ? { content } : {}),
       ...(published !== undefined ? { published } : {}),
+      ...(rerankScore !== undefined ? { rerankScore } : {}),
+      ...(authorityScore !== undefined ? { authority: authorityScore } : {}),
+      ...(siteName ? { siteName } : {}),
     });
   }
 

package/src/core/types.ts

@@ -13,6 +13,12 @@ export interface SearchOptions {
   readonly blockedDomains: readonly string[];
   readonly includeDomains: readonly string[];
   readonly language?: string;
+  /**
+   * Deployment-level only — never a per-call tool parameter. A valid IPv4 or
+   * IPv6 address sent as DeepSeek's optional `localization` to prefer
+   * geo-localized results; invalid values are dropped at option resolution.
+   */
+  readonly localization?: string;
   readonly maxSummaryChars: number;
   readonly timeoutMs: number;
   readonly enabled: boolean;
@@ -46,6 +52,7 @@ export interface ResolvedOptions {
 export interface DeepSeekSearchResult {
   readonly rerank_score?: number;
   readonly authority?: number;
+  readonly site_name?: string | null;
   readonly title?: string | null;
   readonly url?: string | null;
   readonly snippet?: string | null;
@@ -59,6 +66,10 @@ export interface SearchResult {
   readonly title?: string;
   readonly content?: string;
   readonly published?: number;
+  readonly rerankScore?: number;
+  /** Faithful to the wire: -1 means unknown authority. */
+  readonly authority?: number;
+  readonly siteName?: string;
 }
 
 export interface FetchedPage {

package/src/installer/apply.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { dirname } from "node:path";
+import { TOOL_VERSION } from "../version";
 import { codecFor, writeConfig } from "./formats";
 import { deepEqual, valueAt } from "./formats/value";
 import { withOperationLock } from "./operation-lock";
@@ -8,9 +9,9 @@ import { pruneEmptyDir, revertRecordedFile } from "./revert";
 import { deleteRecord, readRecord, statePathFor, writeRecord } from "./state";
 import type { ConfigOp, FileEdit, InstallerInput, InstallPlan, InstallRecord, RecordedFile } from "./types";
 
+/** What a successful apply reports; every failure mode throws instead. */
 export interface ApplyResult {
-  readonly lines: string[];
-  readonly ok: boolean;
+  readonly lines: readonly string[];
 }
 
 /** A failed apply tells callers whether retrying is safe or recovery is still needed. */
@@ -94,6 +95,7 @@ function applyLocked(plan: InstallPlan, input: InstallerInput): ApplyResult {
     lines.push(...verification.lines);
     const record: InstallRecord = {
       version: 1,
+      installerVersion: TOOL_VERSION,
       host: plan.host,
       scope: plan.scope,
       tiers: plan.tiers,
@@ -135,7 +137,7 @@ function applyLocked(plan: InstallPlan, input: InstallerInput): ApplyResult {
       error,
     );
   }
-  return { lines, ok: true };
+  return { lines };
 }
 
 function errorMessage(error: unknown): string {

package/src/installer/cli.ts

@@ -1,9 +1,14 @@
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import { applyPlan } from "./apply";
+import { userConfigHome } from "../core/config-file";
+import type { Env } from "../core/env";
+import { TOOL_VERSION } from "../version";
+import { ApplyError, applyPlan } from "./apply";
+import { runConfigCommand } from "./config-command";
 import { HOST_PLANNERS, HOST_VERSION_PROBES, planForHost } from "./hosts";
+import { pinPackageRef } from "./ownership";
 import { renderPlan } from "./render";
-import { listRecords } from "./state";
+import { legacyGlobalStateDir, listRecords, readingLegacyGlobalRecords } from "./state";
 import type { HostName, InstallerInput, Scope, Tier } from "./types";
 import { uninstall } from "./uninstall";
 
@@ -12,12 +17,18 @@ const HOST_CHOICES = `<${HOSTS.join("|")}>`;
 const SCOPES: readonly Scope[] = ["project", "global"];
 const TIERS: readonly Tier[] = ["optional", "preferred", "forced", "off"];
 
+const EXIT_FAILURE = 1;
+const EXIT_USAGE = 2;
+const EXIT_RECOVERY = 3;
+
 const USAGE = `Usage:
   deepseek-web-retrieval init --host ${HOST_CHOICES} --scope <project|global> \
 --search <optional|preferred|forced|off> --fetch <optional|preferred|forced|off> \
-[--path <extension|mcp>] [--package <npm ref>] [--cwd <dir>] [--apply]
+[--path <extension|mcp>] [--package <npm ref>] [--pin] [--cwd <dir>] [--apply]
   deepseek-web-retrieval uninstall --host ${HOST_CHOICES} --scope <project|global> [--cwd <dir>]
   deepseek-web-retrieval list [--cwd <dir>]
+  deepseek-web-retrieval config [--search <query>]
+  deepseek-web-retrieval version
 
 init prints the full plan (every file, old value → new value) and writes nothing
 until --apply is passed. uninstall restores what the plan applied. --path picks
@@ -25,7 +36,22 @@ the integration mechanism for hosts with more than one (Pi: extension by
 default, mcp for the stdio MCP server). --package overrides the package ref
 written into host config; the Pi extension path turns it into the packages
 source (a bare name is prefixed with npm:, a ref that already starts with npm:
-is written as-is).`;
+is written as-is). --pin appends the running CLI's version to the package ref
+(a ref already ending in a version keeps it), so hosts resolve that exact
+release instead of the latest publish; re-run init --pin to move the pin.
+
+config prints the effective configuration — every knob with its value and its
+source (default, shared file, or environment), resolved the way the MCP server
+resolves it — and exits 1 when the config file or the DEEPSEEK_* environment
+has problems (unknown or rejected keys, unparseable JSON, set-but-unusable
+variable values; a missing file is fine). config --search <query>
+runs one billed search through that configuration to verify the key, config,
+and network end to end; it exits 1 when the key is missing or the search fails.
+
+Exit codes: 0 success; 1 refused or failed with nothing written (a failed apply
+is fully rolled back); 2 invalid command line; 3 recovery required — a failed
+apply could not roll back completely, follow the reported guidance before
+re-running.`;
 
 interface Flags {
   readonly values: Map<string, string>;
@@ -34,7 +60,7 @@ interface Flags {
 }
 
 const VALUE_FLAGS = new Set(["host", "scope", "search", "fetch", "path", "package", "cwd"]);
-const BOOLEAN_FLAGS = new Set(["apply"]);
+const BOOLEAN_FLAGS = new Set(["apply", "pin"]);
 const PATH_CHOICES: readonly ["extension", "mcp"] = ["extension", "mcp"];
 
 function parseFlags(args: readonly string[]): Flags {
@@ -54,6 +80,10 @@ function parseFlags(args: readonly string[]): Flags {
         problems.push(`--${name} does not accept a value; use --${name} to enable it or omit it`);
         continue;
       }
+      if (booleans.has(name)) {
+        problems.push(`--${name} was given more than once`);
+        continue;
+      }
       booleans.add(name);
       continue;
     }
@@ -61,6 +91,10 @@ function parseFlags(args: readonly string[]): Flags {
       problems.push(`unknown flag --${name}`);
       continue;
     }
+    if (values.has(name)) {
+      problems.push(`--${name} was given more than once`);
+      continue;
+    }
     if (eq !== -1) {
       values.set(name, arg.slice(eq + 1));
       continue;
@@ -80,6 +114,8 @@ function parseFlags(args: readonly string[]): Flags {
 export interface CliIo {
   readonly out?: (line: string) => void;
   readonly err?: (line: string) => void;
+  /** Platform the CLI resolves paths for; tests pin "win32" on any host. */
+  readonly platform?: NodeJS.Platform;
 }
 
 /** CLI entry for the init/uninstall/list subcommands; returns the process exit code. */
@@ -87,24 +123,34 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
   const out = io.out ?? ((line: string) => console.log(line));
   const err = io.err ?? ((line: string) => console.error(line));
   const [command, ...rest] = argv;
-  if (command === undefined || command === "help" || command === "--help") {
+  if (command === "version" || command === "--version") {
+    out(TOOL_VERSION);
+    return 0;
+  }
+  if (command === undefined) {
+    err(USAGE);
+    return EXIT_USAGE;
+  }
+  if (command === "help" || command === "--help") {
     out(USAGE);
-    return command === undefined ? 1 : 0;
+    return 0;
   }
   const flags = parseFlags(rest);
   if (flags.problems.length > 0) {
     for (const problem of flags.problems) err(`error: ${problem}`);
     err(`\n${USAGE}`);
-    return 1;
+    return EXIT_USAGE;
   }
   const cwd = resolve(flags.values.get("cwd") ?? process.cwd());
   const home = process.env.HOME ?? homedir();
-  const configHome = resolveConfigHome(home);
+  const platform = io.platform ?? process.platform;
+  const roots = { home, cwd, platform } as const;
+  const configHome = resolveConfigHome(process.env, home, platform);
 
   if (command === "list") {
     let records: ReturnType<typeof listRecords>;
     try {
-      records = listRecords({ home, cwd, configHome });
+      records = listRecords({ ...roots, configHome });
     } catch (error) {
       err(error instanceof Error ? error.message : String(error));
       return 1;
@@ -113,17 +159,28 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
       out("No installs recorded.");
       return 0;
     }
+    if (readingLegacyGlobalRecords({ ...roots, configHome })) {
+      out(
+        `Global install records are being read from the legacy ${legacyGlobalStateDir(roots)} ` +
+          "(written before the Windows config home moved to %APPDATA%).",
+      );
+    }
     for (const record of records) {
+      const by = record.installerVersion ? ` by v${record.installerVersion}` : "";
       out(
-        `${record.host} (${record.scope}) — search=${record.tiers.search}, fetch=${record.tiers.fetch}, installed ${record.createdAt}`,
+        `${record.host} (${record.scope}) — search=${record.tiers.search}, fetch=${record.tiers.fetch}, installed ${record.createdAt}${by}`,
       );
       for (const file of record.files) out(`  ${file.created ? "created" : "modified"} ${file.file}`);
     }
     return 0;
   }
 
+  if (command === "config") {
+    return runConfigCommand(flags.values.get("search"), { out, err });
+  }
+
   if (command === "uninstall") {
-    const required = requireInput(flags, cwd, home, configHome, false);
+    const required = requireInput(flags, cwd, home, configHome, platform, false);
     if (!required.ok) return usageError(required.problems, err);
     try {
       for (const line of uninstall(required.input)) out(line);
@@ -136,10 +193,10 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
 
   if (command !== "init") {
     err(`Unknown command "${command}".\n\n${USAGE}`);
-    return 1;
+    return EXIT_USAGE;
   }
 
-  const required = requireInput(flags, cwd, home, configHome, true);
+  const required = requireInput(flags, cwd, home, configHome, platform, true);
   if (!required.ok) return usageError(required.problems, err);
   const { input } = required;
   const probe = HOST_VERSION_PROBES[input.host];
@@ -158,27 +215,34 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
   try {
     const result = applyPlan(plan, input);
     for (const line of result.lines) out(line);
-    return result.ok ? 0 : 1;
+    return 0;
   } catch (error) {
     err(error instanceof Error ? error.message : String(error));
-    return 1;
+    return exitCodeForError(error);
   }
 }
 
+/** Maps a thrown error to its exit code; recovery is the case a script must not retry blindly. */
+export function exitCodeForError(error: unknown): number {
+  return error instanceof ApplyError && error.status === "recovery_required" ? EXIT_RECOVERY : EXIT_FAILURE;
+}
+
 function usageError(problems: readonly string[], err: (line: string) => void): number {
   for (const problem of problems) err(`error: ${problem}`);
   err(`\n${USAGE}`);
-  return 1;
+  return EXIT_USAGE;
 }
 
 /**
- * XDG_CONFIG_HOME is honored only when it belongs to the real home; the one
- * environment read happens here, at the edge, and flows down as explicit input.
+ * The installer edge's one config-home resolution, built on the canonical
+ * helper (userConfigHome): an inherited XDG_CONFIG_HOME is honored only when it
+ * belongs to the real home — a rewritten HOME must not smuggle in someone
+ * else's config root — and every other case takes the helper's platform
+ * default (win32: %APPDATA% or `<home>\AppData\Roaming`; otherwise ~/.config).
  */
-function resolveConfigHome(home: string): string | undefined {
-  const xdg = process.env.XDG_CONFIG_HOME;
-  if (xdg && home === (process.env.HOME ?? "")) return xdg;
-  return undefined;
+export function resolveConfigHome(env: Env, home: string, platform: NodeJS.Platform = process.platform): string {
+  const xdgTrusted = env.XDG_CONFIG_HOME !== undefined && env.XDG_CONFIG_HOME !== "" && home === (env.HOME ?? "");
+  return userConfigHome({ env: xdgTrusted ? env : { ...env, XDG_CONFIG_HOME: undefined }, home, platform });
 }
 
 type RequireInputResult =
@@ -189,7 +253,8 @@ function requireInput(
   flags: Flags,
   cwd: string,
   home: string,
-  configHome: string | undefined,
+  configHome: string,
+  platform: NodeJS.Platform,
   needsTiers: boolean,
 ): RequireInputResult {
   const problems: string[] = [];
@@ -229,6 +294,7 @@ function requireInput(
   }
   if (home === "") problems.push("HOME is not set and the user home cannot be resolved; cannot proceed");
   if (problems.length > 0) return { ok: false, problems };
+  const packageRef = flags.values.get("package") ?? "deepseek-web-retrieval";
   return {
     ok: true,
     input: {
@@ -236,10 +302,11 @@ function requireInput(
       scope: scope as Scope,
       search: search as Tier,
       fetch: fetch as Tier,
-      packageRef: flags.values.get("package") ?? "deepseek-web-retrieval",
+      packageRef: flags.booleans.has("pin") ? pinPackageRef(packageRef, TOOL_VERSION) : packageRef,
       home,
       cwd,
       configHome,
+      platform,
       ...(path !== undefined ? { path: path as "extension" | "mcp" } : {}),
     },
   };