Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

92.9 KB
Raw Blame
/**
 * Native 1Password integration for claudish.
 *
 * Self-contained, dependency-light module: this is imported by index.ts which
 * runs BEFORE heavy dependencies are loaded. Use ONLY node built-ins (and
 * node:child_process spawnSync, used SOLELY for the optional read-only
 * `op account list` account picker — never for a secret) at module load time.
 * The 1Password SDK is imported DYNAMICALLY (await import) and ONLY when SDK
 * auth is actually available and a secret/field/environment is needed — so a
 * normal claudish run never pulls in the ~10MB SDK + WASM. Do not import zod,
 * hono, the provider registry, or anything else from the proxy stack here.
 *
 * Resolution model (v7.6.0+): SDK-ONLY.
 *  - ALL secret operations — resolving op:// references, discovering an item's
 *    fields for a glob import, and reading 1Password Environments — go through
 *    the official @1password/sdk (beta 0.4.1+, which has the environments API).
 *  - Auth is EITHER a service-account token (OP_SERVICE_ACCOUNT_TOKEN, headless)
 *    OR DesktopAuth using an account name (OP_ACCOUNT / onepasswordAccount config
 *    / a single auto-detected account / an interactively-picked account). The SDK
 *    cannot reuse an interactive `op signin` session, so an `op signin`-only
 *    setup must now set OP_ACCOUNT (DesktopAuth) or a token.
 *  - The ONE remaining `op` binary touch is an OPTIONAL, read-only
 *    `op account list --format=json` used SOLELY to populate the multi-account
 *    picker (it never sees a secret and degrades gracefully when `op` is absent).
 *
 * Entry points (all ASYNC, all SDK-backed):
 *  - resolveSecrets(): batch-resolve { envVar: "op://..." } → { envVar: value }.
 *  - readEnvironment(): read a named 1Password Environment → { name: value }.
 *  - discoverItemFields() / resolveGlobImport(): glob field import (names-first
 *    discovery, then value resolution).
 *  - resolveSdkAuth(): the orchestrated auth resolver (token → OP_ACCOUNT →
 *    config account → single auto-detect → interactive picker → hard-fail).
 *
 * CRITICAL behaviors enforced here:
 *  - Everything stays in-memory. Nothing is written to disk.
 *  - Failures HARD FAIL (the caller calls process.exit(1)) because 1Password
 *    usage here is always explicit opt-in (an `op://` ref or `--op-env`).
 *  - No SDK auth → hard-fail with an actionable error (no `op` CLI fallback).
 */

import { spawnSync } from "node:child_process";
import { realValue } from "../env-placeholder.js";
import { addSpanMeta, beginQueuedSpan, setStartupAuthKind, traceSpan } from "../startup-trace.js";
import { VERSION } from "../version.js";
import { peerHoldsHandshakeLock, withHandshakeLock } from "./onepassword-handshake-lock.js";

/** Matches a full `op://...` secret reference (no embedded whitespace). */
export const OP_REF_RE = /^op:\/\/[^\s]+$/;

/** True when the given string is a 1Password secret reference. */
export function isOpReference(v: string): boolean {
  return typeof v === "string" && OP_REF_RE.test(v);
}

/**
 * Provenance registry for 1Password-hydrated env vars.
 *
 * 1Password keys are resolved at startup and written into `process.env` (see
 * index.ts hydration points). Once there, an op://-sourced key is
 * indistinguishable from a genuine shell env var by `process.env` inspection
 * alone — which made the config TUI mislabel 1Password keys as "From: env".
 *
 * Each hydration site records the env-var names it sourced from 1Password via
 * `recordOpHydratedVars`; UI/provenance code reads `isOpHydratedVar` to show the
 * true source. In-memory is sufficient because both consumers (`claudish config`
 * and `--probe`) run hydration in the SAME process before rendering.
 */
const opHydratedVars = new Set<string>();

/** Record env-var names whose values were hydrated from 1Password. */
export function recordOpHydratedVars(names: Iterable<string>): void {
  for (const n of names) {
    if (typeof n === "string" && n.length > 0) opHydratedVars.add(n);
  }
}

/** True when this env var's value was hydrated from 1Password this run. */
export function isOpHydratedVar(name: string | undefined): boolean {
  return !!name && opHydratedVars.has(name);
}

/**
 * Run-scoped record of 1Password sources that FAILED this run — the negative
 * counterpart to `opHydratedVars`, with the same in-memory rationale (resolution
 * and error rendering happen in one process).
 *
 * Why this exists: every op-source failure is deliberately NON-FATAL (a broken
 * import must never lock the user out — see op-source.ts). It warns and moves
 * on. But the downstream missing-key error is built from the provider
 * resolution alone, so it had no way to know 1Password had been consulted and
 * denied — and told the user to `export` a key they already store in 1Password.
 * Recording the failure here lets `getMissingKeyError` name the real cause.
 *
 * The record is deliberately COARSE (run-scoped, not per-env-var): an
 * Environment fetch is all-or-nothing, so when it fails we cannot know which
 * variables it would have supplied. "1Password failed this run" is the honest
 * claim; attributing it to a specific key would be a guess.
 */
export interface OpSourceFailure {
  /** Which kind of op source failed. */
  kind: "auth" | "environment" | "import" | "reference";
  /** Identifier for the source — an environment id or op:// path. NEVER a value. */
  source?: string;
  /** The underlying SDK/auth error message. */
  message: string;
}

const opSourceFailures: OpSourceFailure[] = [];

/** Record a non-fatal 1Password source failure for later error rendering. */
export function recordOpFailure(failure: OpSourceFailure): void {
  const dup = opSourceFailures.some(
    (f) => f.kind === failure.kind && f.source === failure.source && f.message === failure.message
  );
  if (!dup) opSourceFailures.push(failure);
}

/** All 1Password source failures recorded this run (empty when none). */
export function getOpFailures(): readonly OpSourceFailure[] {
  return opSourceFailures;
}

/** Test seam: clear the run-scoped failure record. */
export function resetOpFailures(): void {
  opSourceFailures.length = 0;
}

/**
 * True when a recorded failure is the user (or a locked Mac) declining the
 * 1Password desktop authorization prompt, as opposed to a missing token,
 * unreachable app, or bad reference. This distinction drives the remediation:
 * a denial means the credential is reachable and just needs approval.
 */
export function wasOpAuthorizationDenied(): boolean {
  return opSourceFailures.some((f) => /denied authorization/i.test(f.message));
}

/**
 * Turn an SDK error into something worth showing a person.
 *
 * The SDK surfaces its Rust error with `Debug` formatting, so a routine denial
 * reaches the user as:
 *
 *   An error occurred when processing SDK request: Error { msg: Denied
 *   authorization for SDK client, inner: None }
 *
 * which names no cause, offers no fix, and reads like a crash. Worse, the four
 * causes of a denial need four different answers, and the struct dump gives the
 * same text for all of them. A probe can still tell them apart at the moment of
 * failure, so ask.
 *
 * FOR DISPLAY ONLY — always record the RAW message. `wasOpAuthorizationDenied`
 * matches on the original wording, and rewriting what gets stored would break
 * the remediation block that depends on it.
 */
export function humanizeOpError(err: unknown): string {
  const raw = (err instanceof Error ? err.message : String(err)).trim();

  if (/denied authorization/i.test(raw)) {
    const cause = currentLockCause();
    if (cause === "screen") return "your Mac is locked, so the approval prompt couldn't be shown";
    if (cause === "app") return "the 1Password app is locked, so it declined without prompting";
    if (cause === "peer") return "another claudish process is holding the 1Password prompt";
    return "the 1Password approval prompt was dismissed (or never answered)";
  }

  // Not a denial: keep the real text, minus the Rust struct wrapper.
  //
  // Anchored on the `, inner:` / `}` that actually terminate the field rather
  // than on "the next comma" — a message like "vault not found, check the
  // reference" is one value containing a comma, and a comma-stopped match would
  // silently truncate it to "vault not found". Non-greedy so the FIRST
  // terminator wins. Anything that doesn't match this exact shape falls through
  // to the raw text, which is the safe direction: too much detail beats a
  // sentence that quietly lost its second half.
  const unwrapped = raw.match(/Error\s*\{\s*msg:\s*(.*?)(?:,\s*inner:|\s*\})/s);
  return (unwrapped?.[1] ?? raw).trim();
}

/**
 * Render the "1Password was consulted and failed" block for a missing-key
 * error. Returns [] when 1Password played no part this run, so the caller can
 * splice unconditionally and non-op users see no change.
 *
 * Placed ABOVE the generic `export FOO=...` remediation by the caller: when a
 * key lives in 1Password, "approve the prompt" is the fix and exporting a
 * literal is the bypass — showing them in the other order taught the wrong
 * lesson (this is the bug from the locked-Mac SSH report).
 */
export function renderOpFailureNotice(envVar: string): string[] {
  return renderOpFailureBlock(`for ${envVar} this run`);
}

/**
 * The same block with a caller-supplied subject phrase.
 *
 * The MCP server needs this without an env-var name. When a tool routes a model
 * and 1Password fails, the only report today is `warnOnce` on STDERR — which an
 * MCP host captures and never shows the user. That is precisely why this whole
 * class of failure presented as silence: claudish was explaining itself into a
 * stream nobody reads. Returning the lines lets the tool RESULT carry them.
 */
export function renderOpFailureBlock(subject: string): string[] {
  if (opSourceFailures.length === 0) return [];

  const lines: string[] = [`1Password was consulted ${subject} and failed:`];
  for (const f of opSourceFailures) {
    const where = f.source ? `${f.kind} ${f.source}` : f.kind;
    lines.push(`  ${where} — ${f.message.split("\n")[0]}`);
  }
  lines.push("");

  if (wasOpAuthorizationDenied()) {
    // Name the SPECIFIC cause when a probe can still see it. A denial has four
    // causes with four different fixes, and "the app declined" sends the user
    // hunting for a prompt that, in the app-locked case, was never shown.
    //
    // Precedence comes from currentLockCause() so this message and the retry
    // classifier can never disagree about which lock to name.
    const cause = currentLockCause();
    if (cause === "screen") {
      lines.push("  Your Mac is locked, so the 1Password approval prompt cannot be shown.");
      lines.push("");
      lines.push("  Fix: unlock the Mac, approve the prompt, and re-run.");
    } else if (cause === "app") {
      lines.push("  The 1Password app is LOCKED. With shared lock state (the default) a locked");
      lines.push("  app refuses the SDK outright — no approval prompt is ever shown, which is");
      lines.push("  why nothing appeared on screen.");
      lines.push("");
      lines.push("  Fix: unlock 1Password (Touch ID is enough) and re-run.");
      lines.push("  To stop it re-locking mid-session, raise Settings → Security → auto-lock.");
    } else if (cause === "peer") {
      lines.push("  Another claudish process is at the 1Password prompt right now. 1Password");
      lines.push("  authorizes ONE client at a time and denies every peer instantly, so this");
      lines.push("  run lost a race rather than being refused.");
      lines.push("");
      lines.push("  Fix: approve the prompt in the other window, then re-run this one.");
    } else {
      lines.push("  The 1Password desktop app declined to release secrets. The approval prompt");
      lines.push("  was most likely dismissed.");
      lines.push("");
      lines.push("  Fix: re-run and approve the 1Password prompt.");
    }
    lines.push("  Headless (no desktop app): export OP_SERVICE_ACCOUNT_TOKEN='ops_...'");
  } else {
    lines.push("  Fix: check the reference resolves — claudish config → 1Password tab.");
    lines.push("  Headless (no desktop app): export OP_SERVICE_ACCOUNT_TOKEN='ops_...'");
  }

  return lines;
}

/** Build the standard actionable auth-failure error. */
export function buildAuthError(detail: string): Error {
  return new Error(
    `${detail}\nSet OP_SERVICE_ACCOUNT_TOKEN (service account, headless) or OP_ACCOUNT (your 1Password account URL, e.g. my-team.1password.com) for the desktop app — or set \`onepasswordAccount\` in ~/.claudish/config.json.`
  );
}

/** Return a masked preview of a secret for safe logging: first 4 chars + "…". */
export function maskSecret(v: string): string {
  if (!v) return "";
  return `${v.slice(0, 4)}…`;
}

// ===========================================================================
// Glob field import (v7.7.0+)
//
// `op://` itself rejects `*` ("invalid character in secret reference"), so a
// glob field import is expanded CLIENT-SIDE: discover field names from ONE
// 1Password item, filter labels/sections by a glob, then resolve only the
// matching fields through the SDK resolve engine. Each matched field's LABEL
// becomes the env var name.
//
// GRAMMAR (segment count after the item determines scope):
//   op://<vault>/<item>/<fieldGlob>               (1 seg)  → match <fieldGlob>
//     against TOP-LEVEL (sectionless) field labels only.
//   op://<vault>/<item>/<sectionGlob>/<fieldGlob> (2 segs) → match fields whose
//     SECTION label matches <sectionGlob>, then filter those by <fieldGlob>.
// A path with NO `*` in the post-item segment(s) is NOT a glob import (the
// single-field op:// path handles it). >2 post-item segments → not supported.
//
// DISCOVERY is now SDK-only (vaults.list → items.list → items.get). The SDK's
// ItemField exposes title/sectionId/fieldType but NO ready-made `reference`, so
// we synthesize each field's op:// reference from the vault/item/section/field
// titles. The SDK decrypts every field value to list field names — that's no
// different from `op item get`, which also decrypts everything in-process. The
// `hasValue` flag we keep records only WHETHER a value is present, never the
// value itself.
// ===========================================================================

/**
 * A discovered 1Password item field — names/metadata + a MASKED value tail.
 *
 * Security note: we deliberately keep NO full value. `valueTail` is only the
 * LAST 4 characters of the value (computed at discovery time, where the SDK has
 * already decrypted everything in-process to list fields) — the standard
 * "•••• 1234" identification pattern (1Password / AWS / Stripe). It lets the
 * user confirm WHICH credential is wired up without exposing the secret. The
 * full value is never stored, returned, or logged.
 */
export interface DiscoveredField {
  /** The field's label, verbatim (may include surrounding whitespace). */
  label: string;
  /** The owning section's label, or null for a top-level (sectionless) field. */
  section: string | null;
  /** The field's full op:// reference (used for value resolution). */
  reference: string;
  /** The field type (CONCEALED, STRING, …). Kept for diagnostics. */
  type: string;
  /** Whether the field has a non-empty value (no value content is kept). */
  hasValue: boolean;
  /** The LAST 4 chars of the value (for "••••1234" display), or "" when none. */
  valueTail: string;
  /**
   * The FULL decrypted value — populated ONLY when discovery is called with
   * `captureValues: true` (the glob-IMPORT path, which needs the value anyway
   * and already pays the in-process decrypt). It is `undefined` on every
   * display/preview call, preserving the "keep no full value" posture there.
   *
   * Why this exists: the SDK returns each field's decrypted `value` during
   * discovery. Re-resolving a synthesized title-based `op://Vault/Item/Section/
   * Title` reference through `secrets.resolveAll()` afterwards is ambiguous —
   * 1Password matches the reference BY TITLE, so a title that recurs across the
   * item fails with `tooManyMatchingFields` and the key is silently skipped.
   * Carrying the value the SDK already decrypted removes that second round-trip
   * and the whole class of title-collision failures.
   */
  value?: string;
}

/** Last 4 chars of a secret, for masked-tail display (empty for short/empty). */
export function valueTail(value: unknown): string {
  if (typeof value !== "string" || value.length === 0) return "";
  return value.slice(-4);
}

/**
 * True when `opPath` is an `op://...` path AND its post-item segment(s) contain
 * a `*` — i.e. it's a glob field import rather than a single-field reference.
 *
 * Parse: strip `op://`, split on `/` → [vault, item, ...rest]. A glob import has
 * 1 or 2 `rest` segments, at least one of which contains `*`. (>2 rest segments
 * → unsupported → false; the single-field op:// path is left untouched.)
 */
export function isGlobImport(opPath: string): boolean {
  if (typeof opPath !== "string" || !opPath.startsWith("op://")) return false;
  const rest = opPath.slice("op://".length).split("/");
  // rest = [vault, item, ...post]
  if (rest.length < 3) return false; // need at least vault/item/oneSegment
  const post = rest.slice(2);
  if (post.length < 1 || post.length > 2) return false;
  return post.some((seg) => seg.includes("*"));
}

/** Parsed components of a glob field-import path. */
export interface GlobImport {
  vault: string;
  item: string;
  /** null → 1-segment (top-level fields). Non-null → 2-segment section glob. */
  sectionGlob: string | null;
  fieldGlob: string;
  /**
   * true → the whole-item `**` form: match EVERY field regardless of section
   * (sectioned AND sectionless). Purely claudish-side syntax (1Password never
   * sees `*`/`**`), so this is free to define. Set only for a lone single-segment
   * `**`; a 2-segment `**`-on-one-axis is an ordinary glob, not match-all.
   */
  matchAll?: boolean;
}

/**
 * Parse an `op://<vault>/<item>/...` glob path into its components. Assumes
 * isGlobImport(opPath) is true (1 or 2 post-item segments).
 *
 *  - 1 post segment `**` → { sectionGlob: null, fieldGlob: "*", matchAll: true }
 *  - 1 post segment      → { sectionGlob: null, fieldGlob: post[0] }
 *  - 2 post segments     → { sectionGlob: post[0], fieldGlob: post[1] }
 */
export function parseGlobImport(opPath: string): GlobImport {
  const rest = opPath.slice("op://".length).split("/");
  const [vault, item, ...post] = rest;
  if (post.length === 1) {
    if (post[0] === "**") {
      // Whole-item match-all: every field, any section or none.
      return { vault, item, sectionGlob: null, fieldGlob: "*", matchAll: true };
    }
    return { vault, item, sectionGlob: null, fieldGlob: post[0] };
  }
  return { vault, item, sectionGlob: post[0], fieldGlob: post[1] };
}

/**
 * Compile a GLOB (not regex) segment into an anchored, case-sensitive RegExp.
 *  - `*` matches any run of characters (including none).
 *  - Every other regex metacharacter is escaped (treated literally).
 *  - Anchored with ^…$ so the WHOLE segment must match.
 */
export function globToRegExp(glob: string): RegExp {
  // Escape regex metachars EXCEPT `*`, then turn `*` into `.*`.
  let out = "";
  for (const ch of glob) {
    if (ch === "*") {
      out += ".*";
    } else if (/[.+?^${}()|[\]\\]/.test(ch)) {
      out += `\\${ch}`;
    } else {
      out += ch;
    }
  }
  return new RegExp(`^${out}$`);
}

/** Valid POSIX-ish env var name: starts with a letter/underscore, then word chars. */
const ENV_VAR_NAME_RE = /^[A-Z_][A-Z0-9_]*$/;

/**
 * Discover all fields of a single 1Password item, returning labels + section
 * labels + synthesized op:// references (NO secret values are kept).
 *
 * SDK path (always used):
 *   vaults.list() → match title===vault → vault ID
 *   items.list(vaultId) → match title===item → item ID
 *   items.get(vaultId, itemId) → fields/sections
 *
 * Duplicate vault/item titles → first match + stderr warning (the SDK gives IDs
 * so the choice is deterministic). The synthesized reference is
 *   op://<vaultTitle>/<itemTitle>/[<sectionTitle>/]<fieldTitle>
 *
 * THROWS (caller hard-fails) when:
 *  - no SDK auth is available
 *  - the vault or item isn't found by title
 *  - the SDK call fails (bad token, expired desktop session, network, …)
 */
export async function discoverItemFields(
  vault: string,
  item: string,
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
    /** Override the stderr warn sink (tests capture warnings). */
    warn?: (msg: string) => void;
    /**
     * Populate `DiscoveredField.value` with the full decrypted value the SDK
     * already returns. ONLY the glob-import path sets this — display/preview
     * callers leave it false so no full value is retained. See DiscoveredField.
     */
    captureValues?: boolean;
  } = {}
): Promise<DiscoveredField[]> {
  const warn = opts.warn ?? ((m: string) => console.error(m));
  const client = await acquireSdkClient(opts, `1Password item discovery for '${item}'`);

  // 1. Find the vault by title.
  const vaults = await traceSpan("op:vaults.list", () => client.vaults.list());
  const vaultMatches = vaults.filter((v) => v.title === vault);
  if (vaultMatches.length === 0) {
    throw new Error(
      `1Password vault '${vault}' not found. ` +
        `Available vaults: ${vaults.map((v) => v.title).join(", ") || "(none)"}.`
    );
  }
  if (vaultMatches.length > 1) {
    warn(
      `[claudish] multiple 1Password vaults titled '${vault}'; using the first ` +
        `(id ${vaultMatches[0].id}).`
    );
  }
  const vaultId = vaultMatches[0].id;

  // 2. Find the item by title within the vault.
  const items = await traceSpan("op:items.list", () => client.items.list(vaultId), { vault });
  const itemMatches = items.filter((i) => i.title === item);
  if (itemMatches.length === 0) {
    throw new Error(
      `1Password item '${item}' not found in vault '${vault}'. ` +
        `Available items: ${
          items
            .map((i) => i.title)
            .slice(0, 12)
            .join(", ") || "(none)"
        }.`
    );
  }
  if (itemMatches.length > 1) {
    warn(
      `[claudish] multiple 1Password items titled '${item}' in vault '${vault}'; ` +
        `using the first (id ${itemMatches[0].id}).`
    );
  }
  const itemId = itemMatches[0].id;

  // 3. Fetch the full item and map fields → DiscoveredField.
  // (Item TITLES are fine in trace meta — they already appear in stderr warns.)
  const full = await traceSpan("op:items.get", () => client.items.get(vaultId, itemId), {
    vault,
    item,
  });
  const out: DiscoveredField[] = [];
  for (const field of full.fields) {
    if (typeof field.title !== "string") continue;
    const section = sectionLabel(full, field.sectionId);
    const reference = `op://${vault}/${item}/${section ? `${section}/` : ""}${field.title}`;
    out.push({
      label: field.title,
      section,
      reference,
      type: typeof field.fieldType === "string" ? field.fieldType : String(field.fieldType ?? ""),
      hasValue: !!field.value,
      valueTail: valueTail(field.value),
      value: opts.captureValues && typeof field.value === "string" ? field.value : undefined,
    });
  }
  return out;
}

/**
 * Like discoverItemFields, but takes the vault/item IDs DIRECTLY — skipping the
 * `vaults.list()` + `items.list()` title-resolution round-trips. The config TUI
 * already has the IDs from its vault/item pickers, so this cuts the field-load
 * from THREE sequential SDK calls to ONE (`items.get`), roughly 3× faster on the
 * desktop-app IPC path. `vaultTitle`/`itemTitle` are only used to synthesize the
 * `op://` reference strings (which are title-based). THROWS on no-auth / failure.
 */
export async function discoverItemFieldsById(
  vaultId: string,
  itemId: string,
  vaultTitle: string,
  itemTitle: string,
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
  } = {}
): Promise<DiscoveredField[]> {
  const client = await acquireSdkClient(opts, `1Password item discovery for '${itemTitle}'`);
  const full = await traceSpan("op:items.get", () => client.items.get(vaultId, itemId), {
    vault: vaultTitle,
    item: itemTitle,
  });
  const out: DiscoveredField[] = [];
  for (const field of full.fields) {
    if (typeof field.title !== "string") continue;
    const section = sectionLabel(full, field.sectionId);
    const reference = `op://${vaultTitle}/${itemTitle}/${section ? `${section}/` : ""}${field.title}`;
    out.push({
      label: field.title,
      section,
      reference,
      type: typeof field.fieldType === "string" ? field.fieldType : String(field.fieldType ?? ""),
      hasValue: !!field.value,
      valueTail: valueTail(field.value),
    });
  }
  return out;
}

/**
 * List the user's 1Password vaults (id + title only). Used by the config TUI's
 * vault picker, the first level of the browse-don't-type add-wizard. Mirrors
 * discoverItemFields' acquireSdkClient usage; THROWS on no-auth / SDK failure.
 */
export async function listVaults(
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
  } = {}
): Promise<{ id: string; title: string }[]> {
  const client = await acquireSdkClient(opts, "1Password vault listing");
  return traceSpan("op:vaults.list", () => client.vaults.list());
}

/**
 * List the items (id + title only) in one vault. Used by the config TUI's item
 * picker (second level). Mirrors discoverItemFields' acquireSdkClient usage;
 * THROWS on no-auth / SDK failure.
 */
export async function listItems(
  vaultId: string,
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
  } = {}
): Promise<{ id: string; title: string }[]> {
  const client = await acquireSdkClient(opts, "1Password item listing");
  return traceSpan("op:items.list", () => client.items.list(vaultId));
}

/**
 * Resolve a field's owning section title from its sectionId, or null when the
 * field is top-level (no sectionId) or the section isn't found.
 */
function sectionLabel(
  item: { sections: { id: string; title: string }[] },
  sectionId?: string
): string | null {
  if (!sectionId) return null;
  const match = item.sections.find((s) => s.id === sectionId);
  return match ? match.title : null;
}

/**
 * The outcome of applying a glob's section/field filter + env-name validation
 * to a discovered field. Used by both resolveGlobImport and the preview command.
 */
export interface GlobFieldMatch {
  /** The discovered field this match describes. */
  field: DiscoveredField;
  /** The trimmed env var name this field would become. */
  envName: string;
  /** True when envName is a valid env var name (else the field is skipped). */
  valid: boolean;
}

/**
 * Apply a parsed glob's section + field filter to discovered fields and compute
 * the candidate env var name (trimmed label) + validity for each survivor.
 * Pure — no I/O — so both resolveGlobImport and the preview command share it.
 *
 * A field survives the filter when:
 *  - section scope matches: sectionGlob===null ⇒ field.section===null; else
 *    field.section!==null AND sectionRegex.test(field.section).
 *  - the field's TRIMMED label matches fieldRegex.
 * Each survivor's envName = label.trim(); valid = ENV_VAR_NAME_RE.test(envName).
 */
export function filterGlobFields(fields: DiscoveredField[], glob: GlobImport): GlobFieldMatch[] {
  const sectionRegex = glob.sectionGlob === null ? null : globToRegExp(glob.sectionGlob);
  const fieldRegex = globToRegExp(glob.fieldGlob);

  const matches: GlobFieldMatch[] = [];
  for (const field of fields) {
    // Section scope.
    if (glob.matchAll) {
      // `**` — every field, any section or none. No section check at all.
    } else if (glob.sectionGlob === null) {
      if (field.section !== null) continue;
    } else {
      if (field.section === null) continue;
      if (!sectionRegex!.test(field.section)) continue;
    }
    // Field-label scope (match against the TRIMMED label so a trailing-space
    // label like "GEMINI_API_KEY " still matches a "*_API_KEY" glob).
    const envName = field.label.trim();
    if (!fieldRegex.test(envName)) continue;
    matches.push({ field, envName, valid: ENV_VAR_NAME_RE.test(envName) });
  }
  return matches;
}

/**
 * Resolve a glob field-import path into a `{ envVarName: secretValue }` map.
 *
 * Pipeline:
 *  1. parse → discover all fields of the item (SDK, names only).
 *  2. filter by section + field glob; envName = trimmed label.
 *  3. drop fields whose trimmed label is NOT a valid env var name (warn on
 *     stderr, do NOT sanitize/convert).
 *  4. resolve the surviving fields' op:// references via resolveSecrets
 *     (SDK, batched, in-memory).
 *
 * THROWS when the glob matches NO importable fields (with a hint listing a few
 * available labels), or when discovery / resolution fails.
 */
export async function resolveGlobImport(
  opPath: string,
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
    /** Override the stderr warn sink (tests capture warnings). */
    warn?: (msg: string) => void;
  } = {}
): Promise<Record<string, string>> {
  const warn = opts.warn ?? ((m: string) => console.error(m));
  const glob = parseGlobImport(opPath);
  // captureValues: read each field's already-decrypted value from discovery so
  // we never re-resolve the synthesized title-based reference (which is
  // ambiguous for items with recurring field titles → `tooManyMatchingFields`).
  const fields = await discoverItemFields(glob.vault, glob.item, {
    sdkFactory: opts.sdkFactory,
    auth: opts.auth,
    env: opts.env,
    warn,
    captureValues: true,
  });
  const matches = filterGlobFields(fields, glob);

  // Build the result directly from the discovered values; warn+skip invalid
  // names. A valid-name field with no value is skipped (nothing to import).
  const resolved: Record<string, string> = {};
  let importable = 0;
  for (const m of matches) {
    if (!m.valid) {
      warn(`[claudish] skipped 1Password field '${m.field.label}' (not a valid env var name)`);
      continue;
    }
    importable++;
    if (typeof m.field.value === "string") resolved[m.envName] = m.field.value;
  }

  if (importable === 0) {
    const available = fields
      .map((f) => f.label.trim())
      .filter((l) => l !== "")
      .slice(0, 8);
    throw new Error(
      `1Password glob '${opPath}' matched no importable fields in '${glob.item}'. ` +
        `Available field labels include: ${available.join(", ") || "(none)"}.`
    );
  }

  return resolved;
}

/**
 * Resolve a glob field-import path into ALL its valid `{ envVarName: value }`
 * pairs — the FULL-glob variant used by op-source's shared per-glob resolution.
 *
 * Same pipeline as resolveGlobImport (discover ONCE → filter → read values)
 * but NON-THROWING on zero matches: `{}` is a legitimate, memoizable outcome
 * for the lazy credential path (the old per-credential
 * resolveGlobImportForEnvVars also returned `{}` silently there — a throw here
 * would turn every "glob currently matches nothing" launch into a retry storm,
 * re-running discovery once per provider). Invalid env-var names are skipped
 * silently (callers pass a quiet warn on this path).
 *
 * VALUES COME FROM DISCOVERY (captureValues): each matched field's value is the
 * one the SDK already decrypted while listing the item — NOT a second
 * `secrets.resolveAll()` pass on a synthesized title-based reference. That
 * second pass matched fields BY TITLE and failed with `tooManyMatchingFields`
 * on any item whose field titles recur (observed in real items), silently
 * dropping the key. Reading the discovered value removes that whole failure
 * class. A matched field with no value is skipped; whole-batch failures (no
 * auth, discovery/IPC error) still propagate — those must NOT be memoized.
 */
export async function resolveGlobImportAll(
  opPath: string,
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
    /** Override the stderr warn sink (tests capture warnings). */
    warn?: (msg: string) => void;
  } = {}
): Promise<Record<string, string>> {
  const warn = opts.warn ?? ((m: string) => console.error(m));
  const glob = parseGlobImport(opPath);
  // captureValues: use the values discovery already decrypted (one SDK call)
  // rather than a second title-based resolveAll pass, which fails with
  // `tooManyMatchingFields` on any item whose field titles recur.
  const fields = await discoverItemFields(glob.vault, glob.item, {
    sdkFactory: opts.sdkFactory,
    auth: opts.auth,
    env: opts.env,
    warn,
    captureValues: true,
  });
  const matches = filterGlobFields(fields, glob);

  const resolved: Record<string, string> = {};
  for (const m of matches) {
    if (!m.valid) continue;
    // A valid-name field with no captured value is silently skipped — matches
    // the previous partial-resolve semantics (one empty field ≠ batch failure).
    if (typeof m.field.value === "string") resolved[m.envName] = m.field.value;
  }

  // Zero importable matches → {} (memoizable, non-throwing — see docblock).
  return resolved;
}

/**
 * Resolve a glob field-import path but SEEK ONLY the env var names in `envNames`.
 *
 * This is the per-credential variant of resolveGlobImport, used by the lazy
 * hydration path: when claudish routes a model that needs a specific (missing)
 * env-var API key, it resolves the op:// glob looking ONLY for THAT key — never
 * decrypting/advertising every field of the item. A glob like
 * `op://Vault/Item/**` therefore resolves to find just the wanted env var(s).
 *
 * Pipeline (mirrors resolveGlobImport, but with a wanted-name filter):
 *  1. parse → discover all fields of the item (SDK, names only).
 *  2. filter by section + field glob; envName = trimmed label.
 *  3. KEEP only valid matches whose envName ∈ `envNames`.
 *  4. resolve the surviving fields' op:// references via resolveSecrets.
 *
 * Returns `{}` when nothing wanted matches (NON-THROWING — unlike
 * resolveGlobImport, an empty result is expected here: a routed model may need a
 * key this particular glob simply doesn't contain). Discovery / resolution
 * failures still propagate.
 */
export async function resolveGlobImportForEnvVars(
  opPath: string,
  envNames: Iterable<string>,
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
    /** Override the stderr warn sink (tests capture warnings). */
    warn?: (msg: string) => void;
  } = {}
): Promise<Record<string, string>> {
  const wanted = new Set(envNames);
  if (wanted.size === 0) return {};

  const warn = opts.warn ?? ((m: string) => console.error(m));
  const glob = parseGlobImport(opPath);
  // captureValues: the seeking filter runs against the values discovery already
  // decrypted — never a second title-based resolve (ambiguous → tooManyMatchingFields).
  const fields = await discoverItemFields(glob.vault, glob.item, {
    sdkFactory: opts.sdkFactory,
    auth: opts.auth,
    env: opts.env,
    warn,
    captureValues: true,
  });
  const matches = filterGlobFields(fields, glob);

  // Keep ONLY valid matches whose env name is one we're seeking.
  const resolved: Record<string, string> = {};
  for (const m of matches) {
    if (!m.valid) continue;
    if (!wanted.has(m.envName)) continue;
    if (typeof m.field.value === "string") resolved[m.envName] = m.field.value;
  }

  // Nothing wanted matched → return empty (this glob doesn't hold the key).
  return resolved;
}

// ===========================================================================
// Config-import collection + --op flag parsing (v7.8.0+)
//
// These are PURE, side-effect-free helpers that index.ts calls. Factored out so
// the routing/parsing logic is unit-testable without process.env or argv games.
// ===========================================================================

/**
 * Derive an env var NAME from a single (non-glob) op:// reference by taking its
 * trailing path segment (the field label) and applying the SAME trim+validate
 * rule that glob imports use for labels. Returns null when the resulting name is
 * not a valid env var name (caller decides whether to warn/error).
 *
 *   op://Jack/My Item/OpenAI/OPENROUTER_API_KEY → "OPENROUTER_API_KEY"
 *   op://Jack/My Item/GOOGLE/GEMINI_API_KEY      → "GEMINI_API_KEY"
 */
export function envNameFromOpRef(opRef: string): string | null {
  if (typeof opRef !== "string" || !opRef.startsWith("op://")) return null;
  const segments = opRef.slice("op://".length).split("/");
  const last = segments[segments.length - 1] ?? "";
  const name = last.trim();
  if (name === "" || !ENV_VAR_NAME_RE.test(name)) return null;
  return name;
}

/**
 * The result of collecting 1Password imports from a config object. `globImports`
 * are full glob paths (resolved later by resolveGlobImport). `opRefs` maps a
 * derived env var name → a single op:// reference (resolved by resolveSecrets).
 */
export interface CollectedConfigImports {
  /** Single op:// references keyed by their derived env var name. */
  opRefs: Record<string, string>;
  /** Glob-import paths (op://.../*) to expand into many env vars. */
  globImports: string[];
  /** Human-readable warnings (e.g. a single ref whose label isn't a valid name). */
  warnings: string[];
}

/**
 * Collect 1Password imports from the typed config. Reads TWO sources:
 *
 *  1. `cfg.apiKeys` — a `{ NAME: value }` map. A single op:// ref VALUE is
 *     collected under its explicit NAME key (the original behavior). Glob VALUES
 *     in apiKeys are NO LONGER specially detected — globs come ONLY from the
 *     dedicated `onepassword` array (a glob sitting in apiKeys is just treated as
 *     a literal value, which the SDK would reject if used).
 *  2. `cfg.onepassword` — a dedicated `string[]` of glob OR single op:// ref
 *     entries. Glob entries → globImports. Single non-glob op:// entries →
 *     resolved with the env name derived from the trailing field label
 *     (envNameFromOpRef); an entry whose label isn't a valid env var name is
 *     skipped with a warning.
 *
 * PURE: reads `cfg` and an optional `env` snapshot (to honor "don't resolve an
 * already-set env var that differs from config"), returns the collected imports.
 * Does NOT mutate process.env or perform any I/O.
 */
export function collectConfigImports(
  cfg: {
    apiKeys?: Record<string, string>;
    onepassword?: string[];
  },
  env: NodeJS.ProcessEnv = process.env
): CollectedConfigImports {
  const opRefs: Record<string, string> = {};
  const globImports: string[] = [];
  const warnings: string[] = [];

  // --- Source 1: apiKeys (explicit NAME → value). Single op:// refs only. ---
  collectApiKeyRefs(cfg.apiKeys, env, opRefs);

  // --- Source 2: the dedicated onepassword array (globs + single refs). ---
  if (Array.isArray(cfg.onepassword)) {
    for (const entry of cfg.onepassword) {
      collectOnepasswordEntry(entry, env, opRefs, globImports, warnings);
    }
  }

  return { opRefs, globImports, warnings };
}

/**
 * Collect single op:// refs from an `apiKeys` map into `opRefs` (keyed by the
 * explicit NAME). The config value seeds process.env only if not already set;
 * then we resolve whatever is current IF it's a single op:// ref. Mirrors the
 * original gap-fill semantics; the caller applies the env mutation.
 */
function collectApiKeyRefs(
  apiKeys: Record<string, string> | undefined,
  env: NodeJS.ProcessEnv,
  opRefs: Record<string, string>
): void {
  if (!apiKeys) return;
  for (const [envVar, value] of Object.entries(apiKeys)) {
    if (typeof value !== "string") continue;
    const current = env[envVar] ?? value;
    if (isOpReference(current)) {
      opRefs[envVar] = current;
    }
  }
}

/**
 * Classify ONE `onepassword[]` entry: a glob → globImports; a single op:// ref
 * (named by its trailing field label) → opRefs; anything else → a warning.
 */
function collectOnepasswordEntry(
  entry: unknown,
  env: NodeJS.ProcessEnv,
  opRefs: Record<string, string>,
  globImports: string[],
  warnings: string[]
): void {
  if (typeof entry !== "string") return;
  const trimmed = entry.trim();
  if (trimmed === "") return;

  if (isGlobImport(trimmed)) {
    globImports.push(trimmed);
    return;
  }

  // A single op:// ref. We DON'T use isOpReference here (its anchored regex
  // rejects whitespace, but real item/section labels contain spaces). The
  // `op://` prefix is enough; envNameFromOpRef validates the trailing label.
  if (trimmed.startsWith("op://")) {
    const name = envNameFromOpRef(trimmed);
    if (name === null) {
      warnings.push(
        `[claudish] skipped 1Password ref '${trimmed}' from onepassword[] (its trailing field label is not a valid env var name)`
      );
      return;
    }
    // Single refs from onepassword[] DON'T overwrite an already-set env var.
    if (!env[name]) {
      opRefs[name] = trimmed;
    }
    return;
  }

  warnings.push(
    `[claudish] skipped 1Password entry '${trimmed}' from onepassword[] (not a glob import or op:// reference)`
  );
}

/**
 * Parse the `--op <glob>` early-hydration flag out of a raw argv slice. PURE —
 * takes `process.argv.slice(2)`-shaped input and extracts the glob value plus
 * the `--list` modifier. Used by index.ts's `applyOpImport()` (and tested in
 * isolation so the matching/collision rules are pinned).
 *
 * Matching rules (deliberately strict to avoid the `--op-env` collision):
 *  - The flag token is matched by EXACT equality `=== "--op"` (value is the next
 *    argv entry) OR by the `--op=` prefix (`startsWith("--op=")`, inline value).
 *    A naive `startsWith("--op")` would WRONGLY swallow `--op-env`/`--op-list`;
 *    we never use that.
 *  - `--op-env` and any other `--op<suffix>` token is NOT matched as `--op`.
 *  - `--list` is matched as a bare token anywhere in argv (the preview modifier).
 *
 * Returns:
 *  - `glob`: the op:// glob value (verbatim — it may contain spaces because the
 *    shell already delivered it as ONE argv entry), or undefined when `--op` is
 *    absent. When `--op` is present but its value is missing/empty/another flag,
 *    `glob` is undefined and `present` is true so the caller can emit a usage
 *    error.
 *  - `list`: true when a bare `--list` token is present.
 *  - `present`: true when a `--op`/`--op=` token appears at all (lets the caller
 *    distinguish "no --op" from "--op with a bad value").
 */
export interface ParsedOpFlag {
  /** The op:// glob value (verbatim), or undefined when none/invalid. */
  glob: string | undefined;
  /** True when a bare `--list` token is present → preview-and-exit. */
  list: boolean;
  /** True when a `--op`/`--op=` token appears (even with a missing value). */
  present: boolean;
}

export function parseOpFlag(argv: string[]): ParsedOpFlag {
  let glob: string | undefined;
  let present = false;
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    // EXACT match — `--op <value>`. Must not match `--op-env`, `--op-list`, etc.
    if (a === "--op") {
      present = true;
      const next = argv[i + 1];
      // A missing value, an empty value, or another flag → invalid (glob stays
      // undefined; caller emits a usage error because `present` is true).
      if (next !== undefined && next !== "" && !next.startsWith("-")) {
        glob = next;
      }
      break;
    }
    // Inline form — `--op=<value>`. `startsWith("--op=")` cannot match `--op-env`
    // (no `=` there) so this is safe.
    if (a.startsWith("--op=")) {
      present = true;
      const v = a.slice("--op=".length);
      if (v !== "") glob = v;
      break;
    }
  }
  const list = argv.includes("--list");
  return { glob, list, present };
}

// ===========================================================================
// SDK layer (v7.6.0+) — SDK-ONLY
//
// Everything below is the ASYNC public surface. The SDK is loaded via a
// DYNAMIC import so a normal run never touches the ~10MB SDK + WASM. The entry
// points — resolveSecrets / readEnvironment / discoverItemFields — require SDK
// auth and hard-fail (no `op` CLI fallback) when none is available.
// ===========================================================================

/**
 * The minimal subset of the @1password/sdk Client we use. Defined locally so
 * tests can inject a fake without importing the real (heavy) SDK, and so the
 * SDK import stays dynamic. The real client structurally satisfies these (the
 * SDK's richer field types — e.g. `fieldType: ItemFieldType` — narrow to our
 * `string` via the `as unknown as SdkClientLike` cast in the default factory).
 */
export interface SdkClientLike {
  secrets: {
    resolve(secretReference: string): Promise<string>;
    resolveAll(secretReferences: string[]): Promise<{
      // Keyed by the secret reference string (the op://... value), NOT our env
      // var name. Each entry has `content` on success and/or `error` on failure.
      individualResponses: Record<string, { content?: { secret: string }; error?: unknown }>;
    }>;
  };
  vaults: {
    list(): Promise<{ id: string; title: string }[]>;
  };
  items: {
    list(vaultId: string): Promise<{ id: string; title: string }[]>;
    get(
      vaultId: string,
      itemId: string
    ): Promise<{
      id: string;
      title: string;
      fields: { id: string; title: string; sectionId?: string; fieldType: string; value: string }[];
      sections: { id: string; title: string }[];
    }>;
  };
  environments: {
    getVariables(
      environmentId: string
    ): Promise<{ variables: { name: string; value: string; masked: boolean }[] }>;
  };
}

/**
 * Auth descriptor for the SDK. Either a service-account token string, or a
 * DesktopAuth-style account name. Mirrors the SDK's `Auth = string | DesktopAuth`.
 */
export type SdkAuth = { kind: "token"; token: string } | { kind: "desktop"; accountName: string };

/**
 * Injectable factory for the SDK client (the test seam). The default
 * implementation dynamically imports @1password/sdk and builds a real client;
 * tests inject a fake that never touches the SDK or a real token.
 */
export type SdkClientFactory = (auth: SdkAuth) => Promise<SdkClientLike>;

/**
 * Process-lifetime cache of built SDK clients, keyed by auth identity. Reusing
 * ONE client across operations avoids a fresh `createClient` (and a new desktop
 * IPC handshake) on every vault/item/field call. Repeated handshakes are what
 * make the desktop app's IPC flaky (errno -4 / "Denied") under the rapid
 * sequence of calls the config TUI makes — one client, reused, is far steadier
 * and faster. Keyed so a multi-account run never crosses clients.
 */
const sdkClientCache = new Map<string, Promise<SdkClientLike>>();

function sdkAuthCacheKey(auth: SdkAuth): string {
  return auth.kind === "token" ? `token:${auth.token}` : `desktop:${auth.accountName}`;
}

/**
 * Default SDK client factory. DYNAMICALLY imports @1password/sdk (so the WASM
 * is only loaded when we actually have auth + a secret to resolve) and builds
 * an authenticated client — then CACHES it per auth identity so subsequent
 * operations reuse the same client (one desktop IPC handshake, not one per call).
 * The cached value is the in-flight Promise so concurrent first calls dedupe.
 */
export const defaultSdkClientFactory: SdkClientFactory = async (auth) => {
  const key = sdkAuthCacheKey(auth);
  const cached = sdkClientCache.get(key);
  if (cached) return cached;

  const build = (async () => {
    // Ensure the SDK's core_bg.wasm is loadable BEFORE importing the SDK. In a
    // compiled binary the bundled loader points at a stale build-machine path;
    // this installs a readFileSync redirect (and, cold-cache, downloads the
    // pinned WASM from the official npm registry). Zero network on npm installs
    // and on warm caches. See providers/onepassword-wasm.ts.
    // Startup-trace: the dynamic SDK import is the ~10MB WASM load — one of the
    // dominant cold-start costs, so it gets its own span.
    const { createClient, DesktopAuth } = await traceSpan("op:sdk-wasm-import", async () => {
      const { ensureOpWasmAvailable } = await import("./onepassword-wasm.js");
      await ensureOpWasmAvailable();
      return import("@1password/sdk");
    });
    // Startup-trace: the DesktopAuth handshake can block on the USER clicking
    // "Authorize" in the 1Password app — hence mayIncludeUserPrompt.
    //
    // DesktopAuth ONLY: 1Password arbitrates this handshake across the whole
    // machine and denies every concurrent peer, so sibling claudish processes
    // must take turns — see onepassword-handshake-lock.ts for the measurements.
    // A service-account TOKEN is authorized by the value alone, with no desktop
    // app in the loop and nothing to arbitrate, so it never pays for the lock.
    const build = () =>
      createClient({
        auth: auth.kind === "token" ? auth.token : new DesktopAuth(auth.accountName),
        integrationName: "claudish",
        integrationVersion: VERSION || "1.0.0",
      });
    const client = await traceSpan(
      "op:client-handshake",
      () => (auth.kind === "token" ? build() : withHandshakeLock(build)),
      { mayIncludeUserPrompt: true, authKind: auth.kind }
    );
    // The real Client structurally satisfies SdkClientLike (secrets / vaults /
    // items / environments); narrow via unknown to avoid importing SDK types here.
    return client as unknown as SdkClientLike;
  })();

  // Cache the in-flight promise so concurrent callers share one build; on
  // failure, evict so a later call can retry with a fresh handshake.
  sdkClientCache.set(key, build);
  build.catch(() => sdkClientCache.delete(key));
  return build;
};

/**
 * Evict all cached SDK clients so the next operation rebuilds (a fresh desktop
 * IPC handshake). Call this after a transient IPC failure — a cached client
 * whose desktop connection went bad will keep failing until rebuilt.
 */
export function resetSdkClientCache(): void {
  sdkClientCache.clear();
}

/** True when an error looks like a TRANSIENT desktop-IPC failure (errno -4,
 *  "IPC operation failed", broken pipe, stale session) worth one rebuild+retry.
 *  A user DECLINING the desktop prompt ("Denied authorization for SDK client")
 *  is NOT transient — see the terminal guard below — because retrying it just
 *  re-opens the dialog they just cancelled. */
export function isTransientSdkError(err: unknown): boolean {
  const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
  // TERMINAL: the user cancelled the 1Password desktop authorization prompt.
  // That is a deliberate decision, not a transient blip — retrying re-prompts
  // them right after they clicked Cancel (the "second dialog" bug). Never retry.
  if (msg.includes("denied authorization")) return false;
  return (
    msg.includes("ipc operation failed") ||
    msg.includes("ipc operation") ||
    msg.includes("-4") ||
    msg.includes("denied") ||
    msg.includes("broken pipe") ||
    msg.includes("connection") ||
    // Stale DESKTOP SESSION after idle: the cached SDK client's session expires
    // and the next call fails with "invalid client id" / "invalid session" /
    // "session expired". Resetting the cache rebuilds the client (a fresh
    // DesktopAuth handshake), so these are retryable, not hard failures.
    msg.includes("invalid client id") ||
    msg.includes("invalid client") ||
    msg.includes("invalid session") ||
    msg.includes("session expired") ||
    msg.includes("session not found") ||
    msg.includes("unauthorized") ||
    msg.includes("token expired") ||
    msg.includes("not authenticated")
  );
}

/**
 * Process-wide SDK SERIALIZER. The 1Password SDK's WASM↔desktop-app IPC bridge
 * is NOT safe for concurrent calls on a shared client: two operations in flight
 * at once corrupt the channel → "IPC operation failed: -4". The config TUI fires
 * overlapping calls (e.g. a post-save confirm AND the list's glob-expansion at
 * the same moment), which reliably triggers it. We chain every SDK operation
 * onto one promise so AT MOST ONE runs at a time. Calls still complete; they just
 * queue. This is the real fix for -4 (the client cache + retry alone can't help
 * when both concurrent calls fail together).
 */
let sdkQueue: Promise<unknown> = Promise.resolve();
function runSdkExclusive<T>(
  op: () => Promise<T>,
  label = "op:sdk-op",
  meta?: Record<string, string | number | boolean>
): Promise<T> {
  // Startup-trace: one span per queued op recording BOTH the queue wait
  // (enqueue → start, i.e. time spent behind other serialized SDK ops) and the
  // execution (start → finish). A slow launch caused by queue PILE-UP shows a
  // big waitMs; one slow IPC call shows a big execMs.
  const span = beginQueuedSpan(label, meta);
  const timedOp = () => {
    span.start();
    return op();
  };
  const run = sdkQueue.then(timedOp, timedOp); // run after the prior op settles (ok or not)
  run.then(
    () => span.end(),
    (err) => span.end({ error: true, errorMsg: String(err).split("\n")[0].slice(0, 120) })
  );
  // Keep the chain alive regardless of this op's outcome; swallow here so a
  // rejected op doesn't poison the queue for the next caller.
  sdkQueue = run.then(
    () => undefined,
    () => undefined
  );
  return run;
}

/** Sleep helper for the retry backoff (gives the desktop bridge a moment). */
function sdkSleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// ── Locked-screen denial recovery ───────────────────────────────────────────
// 1Password returns the SAME error ("Denied authorization for SDK client") for
// two very different situations:
//   (a) the user was shown the approval dialog and clicked Cancel — a decision;
//   (b) the Mac was LOCKED, so the dialog could not be shown at all and
//       1Password auto-denied — an environmental condition.
// The error alone cannot distinguish them, which is why the denial is pinned
// TERMINAL in isTransientSdkError (retrying (a) re-opens a dialog the user just
// dismissed — the "second dialog" bug). Probing the screen-lock state resolves
// the ambiguity from the OUTSIDE: if the screen is locked, nobody could have
// clicked Cancel, so a retry is legitimate and we wait for the user to unlock.

/** How many unlock countdowns (and therefore retries) a locked denial gets. */
const LOCK_RETRY_ROUNDS = 3;
/** Seconds per countdown — 3 × 10s ≈ 30s total to unlock and approve. */
const LOCK_RETRY_SECONDS = 10;

// The countdown is deliberately human-paced, which makes the full 3-round path
// a 30-second wall-clock event — unacceptable inside a test suite. This seam
// lets tests compress the clock without weakening what they cover: rounds and
// per-round seconds stay independent, so the round COUNT is still asserted
// against the real constant while the seconds shrink to milliseconds.
let lockRetrySeconds = LOCK_RETRY_SECONDS;
let lockTickMs = 1000;

/** Test seam: compress the unlock countdown. Call with no args to restore. */
export function setLockRetryTiming(opts?: { seconds?: number; tickMs?: number }): void {
  lockRetrySeconds = opts?.seconds ?? LOCK_RETRY_SECONDS;
  lockTickMs = opts?.tickMs ?? 1000;
}

// Styling is applied ONLY when stderr is a real terminal. Under an MCP host or
// a MCP session stderr is a captured pipe, where raw escape codes turn a
// helpful message into noise in the log.
const styled = (code: string, s: string): string =>
  process.stderr.isTTY === true ? `\x1b[${code}m${s}\x1b[0m` : s;
const bold = (s: string): string => styled("1", s);
const dim = (s: string): string => styled("2", s);

/** Probe returning true when the macOS screen is locked. Injectable for tests. */
export type ScreenLockProbe = () => boolean;

/**
 * macOS screen-lock probe. `ioreg -n Root -d1 -a` renders the console session
 * as an XML plist; `CGSSessionScreenIsLocked` is present ONLY while the screen
 * is locked (absent entirely when unlocked). ~15ms, no dependencies, and it
 * only ever runs on the denial path — zero cost on a normal run.
 *
 * Non-darwin returns false: DesktopAuth exists on other platforms, but there is
 * no equivalent probe, so those users keep today's terminal behavior.
 */
export const defaultScreenLockProbe: ScreenLockProbe = () => {
  if (process.platform !== "darwin") return false;
  try {
    const res = spawnSync("ioreg", ["-n", "Root", "-d1", "-a"], {
      encoding: "utf-8",
      timeout: 2000,
    });
    if (res.status !== 0 || typeof res.stdout !== "string") return false;
    return /CGSSessionScreenIsLocked<\/key>\s*(?:<true\/>|<integer>1<\/integer>)/.test(res.stdout);
  } catch {
    // Probe failure must never invent a lock — fall back to terminal behavior.
    return false;
  }
};

let screenLockProbe: ScreenLockProbe = defaultScreenLockProbe;

/** Test seam: swap the screen-lock probe. Pass undefined to restore the default. */
export function setScreenLockProbe(probe: ScreenLockProbe | undefined): void {
  screenLockProbe = probe ?? defaultScreenLockProbe;
}

/** True when the macOS screen is currently locked. */
export function isScreenLocked(): boolean {
  return screenLockProbe();
}

// ─── 1Password APP lock (a FOURTH denial cause) ──────────────────────────────
//
// `Denied authorization for SDK client` has a fourth cause, distinct from the
// three above (Cancel / screen locked / concurrent spawn): the 1Password APP
// itself is locked.
//
// When `developers.sdkSharedLockState.enabled` is on — it is by default — the SDK
// is authorized only while the app is unlocked. Once the app auto-locks, the SDK
// is denied IMMEDIATELY and NO dialog is shown, so:
//   · the screen-lock probe stays silent (the screen is unlocked)
//   · it is not a Cancel (nobody was asked)
//   · so the denial was classified terminal, and the user got
//     "GLM/Zhipu API Key is required — export ZHIPU_API_KEY" for a key that
//     is sitting in 1Password.
//
// Measured 2026-07-30: app unlocked 09:29:59, askUnlockAfter 480s, probed at
// 10:35 after 65 min idle → locked; screen unlocked; no 1Password window on
// screen; the SDK call failed in well under the time a human prompt would take.
//
// This is the CHEAPEST of the probes — a single JSON read, no subprocess — and
// like the others it only ever runs on the denial path.

/** Probe returning true when the 1Password app is locked. Injectable for tests. */
export type AppLockProbe = () => boolean;

/**
 * The lock decision, as a PURE function of the settings object and the clock.
 *
 * ⚠️ FALSIFIED — retained only as documentation of an approach that does NOT work.
 * `defaultAppLockProbe` no longer calls this. See its comment for the evidence.
 *
 * Split out from the file read so the rule is testable without touching the
 * developer's real 1Password settings — reading those would make the result
 * depend on whether the machine's app happened to be locked when the suite ran.
 */
export function appLockedFromSettings(settings: unknown, nowSeconds: number): boolean {
  if (typeof settings !== "object" || settings === null) return false;
  const s = settings as Record<string, unknown>;

  // If the SDK does NOT share the app's lock state, app lock cannot be the cause
  // of an SDK denial — say so rather than sending the user to unlock something
  // irrelevant.
  if (s["developers.sdkSharedLockState.enabled"] !== true) return false;

  const last = s["security.authenticatedUnlock.deviceBasedUnlock.lastUnlock"];
  const after = s["security.authenticatedUnlock.deviceBasedUnlock.askUnlockAfter"];
  if (typeof last !== "number" || typeof after !== "number") return false;

  return nowSeconds - last > after;
}

/**
 * INERT: always reports "not locked". App-lock detection is unimplemented.
 *
 * A first attempt derived it from the desktop app's settings.json, computing
 * `now - security.authenticatedUnlock.deviceBasedUnlock.lastUnlock >
 * ...askUnlockAfter`. Direct observation falsified it on 2026-07-30:
 *
 *   · settings.json's mtime was 09:29:59 and `lastUnlock` read 09:29:59 — the file
 *     is not rewritten on unlock, so the timestamp is frozen at the last settings
 *     SAVE, not the last unlock. It is not a live signal at all.
 *   · At 13:04 the same app served every secret through the user's op-backed
 *     .env pipe while that formula computed "locked, 13006s idle".
 *   · `askUnlockAfter` (480s) is the device-unlock re-prompt grace, NOT the app
 *     auto-lock — that is `security.autolock.minutes` (60). Two different things.
 *
 * A probe must never INVENT a lock: a false positive relabels an unrelated denial
 * as "go unlock 1Password" and adds a ~30s countdown the user cannot resolve that
 * way, which is worse than the plain error. So this returns false until a signal
 * is verified, and the `LockCause`/countdown/messaging plumbing around it stays
 * ready for one to drop in via `setAppLockProbe`.
 *
 * Candidates not yet validated: `op whoami` behaviour while
 * `developers.cliSharedLockState.enabled` is on (it did report "account is not
 * signed in" during a denial, but that needs the `op` binary and may itself
 * prompt); the agent socket; or timing — a denial returned faster than any human
 * could answer a dialog implies nobody was asked.
 *
 * NOTE the underlying denial was real; only this attribution of its cause was not.
 */
export const defaultAppLockProbe: AppLockProbe = () => false;

let appLockProbe: AppLockProbe = defaultAppLockProbe;

/** Test seam: swap the app-lock probe. Pass undefined to restore the default. */
export function setAppLockProbe(probe: AppLockProbe | undefined): void {
  appLockProbe = probe ?? defaultAppLockProbe;
}

/** True when the 1Password app is locked AND that gates the SDK. */
export function isAppLocked(): boolean {
  return appLockProbe();
}

/** Probe returning true when a live peer holds the handshake. Injectable. */
export type PeerLockProbe = () => boolean;

let peerLockProbe: PeerLockProbe = peerHoldsHandshakeLock;

/**
 * Test seam: swap the peer probe. Pass undefined to restore the default.
 *
 * MANDATORY for any test that asserts a denial is terminal. The default probe
 * reads a real file under `~/.claudish`, so without this seam the result
 * depends on whether an unrelated claudish happens to be mid-handshake on the
 * developer's machine — which is exactly how this seam got written: a sibling
 * worktree's live run turned "unlocked denial is terminal" into a 30-second
 * countdown.
 */
export function setPeerLockProbe(probe: PeerLockProbe | undefined): void {
  peerLockProbe = probe ?? peerHoldsHandshakeLock;
}

/** True when another live claudish process currently holds the 1Password prompt. */
export function isPeerHoldingPrompt(): boolean {
  return peerLockProbe();
}

/**
 * Which recoverable lock caused a denial, or null when it is terminal.
 *
 * `peer` is not a lock on the MACHINE but on the handshake: another live
 * claudish process is at the 1Password prompt right now. It belongs here
 * because it satisfies the same test the other two do — the user can still get
 * a successful resolve out of this, by waiting.
 */
export type LockCause = "screen" | "app" | "peer";

/**
 * Which lock is currently blocking, in the order the user must clear them.
 *
 * SINGLE source of the precedence rule — both the retry classifier and the error
 * notice call this, so they cannot drift. They already had: an earlier version
 * checked screen-first for retries and app-first for the message, which told a
 * user with a locked Mac to "unlock 1Password", a step they cannot take until
 * the Mac is open.
 *
 * Screen first is the correct order: a locked Mac makes the app unreachable
 * regardless of the app's own state, so the Mac is the actionable blocker.
 */
export function currentLockCause(): LockCause | null {
  if (isScreenLocked()) return "screen";
  if (isAppLocked()) return "app";
  // Last: a peer only matters once the machine itself is not the blocker.
  // Waiting behind a sibling is pointless while the Mac is locked, because the
  // sibling cannot finish either.
  if (isPeerHoldingPrompt()) return "peer";
  return null;
}

/**
 * Classify a denial into the lock the user can still clear, or null if none.
 *
 * A service-account token short-circuits everything: token auth never shows a
 * desktop prompt, so a denial under a token means something else entirely
 * (revoked token, vault access) and waiting for an unlock would be theatre.
 */
export function classifyLockedDenial(
  err: unknown,
  env: NodeJS.ProcessEnv = process.env
): LockCause | null {
  const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
  if (!msg.includes("denied authorization")) return null;
  if (env.OP_SERVICE_ACCOUNT_TOKEN) return null;
  return currentLockCause();
}

/**
 * True when an error is a denial the user could plausibly still approve.
 *
 * Retained as the boolean form of `classifyLockedDenial` — callers that only ask
 * "is this worth waiting on?" keep working unchanged.
 */
export function isLockedDenial(err: unknown, env: NodeJS.ProcessEnv = process.env): boolean {
  return classifyLockedDenial(err, env) !== null;
}

/**
 * Explain the locked denial, then count down before retrying — giving the user
 * time to walk over, unlock, and approve. Returns "cancel" if they bail out.
 *
 * Cancellation degrades by capability rather than by mode (interactive and
 * non-interactive must behave identically): with a TTY stdin, Esc/q/Ctrl-C
 * cancel; without one (e.g. `--stdin < file`), Ctrl-C still works via SIGINT.
 * The countdown itself always renders, so a piped run shows the same story.
 *
 * The live `\r` redraw is used ONLY when stderr is a TTY. Under an MCP host or
 * a MCP session stderr is a captured pipe, where carriage returns produce
 * an unreadable log — those get one static line per round instead.
 */
async function countdownForUnlock(
  round: number,
  rounds: number,
  cause: LockCause
): Promise<"retry" | "cancel" | "skip"> {
  const ttyOut = process.stderr.isTTY === true;
  const ttyIn = process.stdin.isTTY === true;
  let cancelled = false;
  let skipped = false;

  // The explanation prints ONCE, on the first round. Rounds 2 and 3 get only
  // the countdown line — re-explaining the same situation every 10 seconds
  // reads as nagging, and the user is (hopefully) already walking to their Mac.
  //
  // The two causes need DIFFERENT instructions. Telling someone to "approve the
  // popup" when the app is locked is wrong twice over: there is no popup (a
  // locked app denies silently), and the action they need is to unlock 1Password.
  if (round === 1) {
    const explain =
      cause === "screen"
        ? `${bold("🔐 1Password needs your OK — but your Mac is locked, so it can't ask.")}\n   Unlock your Mac and approve the popup. Claudish picks it up from there.`
        : cause === "app"
          ? `${bold("🔐 1Password is locked, so it turned claudish away without asking you.")}\n   Unlock 1Password (Touch ID is enough). Claudish retries on its own —\n   no popup will appear until it's unlocked.`
          : // "peer": nothing is wrong and there is nothing to fix — another
            // claudish already has the prompt, and 1Password authorizes exactly
            // one client at a time. Saying "approve the popup" here would send
            // the user looking for a second popup that will never exist.
            `${bold("🔐 Another claudish is already at the 1Password prompt.")}\n   1Password only lets one through at a time, so this run has to queue.\n   Approve it in the other window (or wait — it usually takes a second).`;
    process.stderr.write(`\n${explain}\n\n`);
  }

  // Wait on the lock that actually caused this denial. Polling the wrong one
  // would either never clear or clear while the real blocker remains.
  const stillLocked = () =>
    cause === "screen" ? isScreenLocked() : cause === "app" ? isAppLocked() : isPeerHoldingPrompt();

  let restoreInput = () => {};
  if (ttyIn) {
    const onKey = (buf: Buffer) => {
      const k = buf.toString();
      // Esc, q, or Ctrl-C — Ctrl-C is handled here too so raw mode can't eat it.
      if (k === "\x1b" || k === "q" || k === "\x03") cancelled = true;
      // `s` is a DIFFERENT decision from cancelling, and the difference is
      // scope: cancel abandons this one wait (a later provider may prompt
      // again, which is the right call if the user is about to approve),
      // whereas skip means "stop asking me about 1Password for this run".
      if (k === "s" || k === "S") skipped = true;
    };
    const wasRaw = process.stdin.isRaw === true;
    try {
      process.stdin.setRawMode(true);
      process.stdin.resume();
      process.stdin.on("data", onKey);
      restoreInput = () => {
        process.stdin.off("data", onKey);
        process.stdin.setRawMode(wasRaw);
        process.stdin.pause();
      };
    } catch {
      restoreInput = () => {};
    }
  }

  // Both exits are always offered, because "wait" is not always the answer the
  // user wants and a countdown with no way out is a hang with a progress bar.
  const stop = ttyIn ? "Esc stop waiting" : "Ctrl-C stop waiting";
  const skip = ttyIn ? " · s skip 1Password" : "";
  // A filled/empty bar makes the remaining wait legible at a glance, which a
  // bare number does not — the point of the countdown is to tell someone
  // walking back to their Mac whether they have time.
  const bar = (secs: number) => {
    const total = Math.max(1, lockRetrySeconds);
    const filled = Math.round(((total - secs) / total) * 10);
    return `${"━".repeat(filled)}${"─".repeat(Math.max(0, 10 - filled))}`;
  };
  const line = (secs: number) =>
    dim(`   ${bar(secs)} ${secs}s · try ${round}/${rounds} · ${stop}${skip}`);
  if (!ttyOut) process.stderr.write(`${line(lockRetrySeconds)}\n`);

  try {
    for (let remaining = lockRetrySeconds; remaining > 0; remaining--) {
      if (cancelled || skipped) break;
      // Cleared early? Don't make the user wait out the clock — retry now, so
      // approving is immediately followed by the prompt they expect.
      if (!stillLocked()) break;
      if (ttyOut) process.stderr.write(`\r\x1b[2K${line(remaining)}`);
      await sdkSleep(lockTickMs);
    }
  } finally {
    restoreInput();
    if (ttyOut) process.stderr.write("\r\x1b[2K");
  }

  if (skipped) {
    process.stderr.write(
      "   Skipping 1Password for this run. Keys already in your environment still work;\n" +
        "   anything only 1Password has will report as missing.\n"
    );
    return "skip";
  }
  if (cancelled) {
    process.stderr.write("   OK, not waiting. You can unlock and re-run any time.\n");
    return "cancel";
  }
  return "retry";
}

/**
 * True only when the `s` skip in `countdownForUnlock` is what set
 * `CLAUDISH_DISABLE_OP`. A user who exported the variable themselves has made a
 * standing decision, and `clearOpSkip` must not overrule it — hence a latch
 * rather than an unconditional `delete process.env.CLAUDISH_DISABLE_OP`.
 */
let opSkipLatchedByPrompt = false;

/** Disable 1Password for the rest of this process, recording that WE did it. */
function latchOpSkip(): void {
  opSkipLatchedByPrompt = true;
  process.env.CLAUDISH_DISABLE_OP = "1";
}

/**
 * Re-arm 1Password after an interactive skip. Returns true when a skip was
 * actually cleared.
 *
 * "Skip 1Password for this run" is the right scope for a one-shot CLI
 * invocation, which ends minutes later. `claudish config` is the opposite: it is
 * a long-lived process, so a skip taken during one "Test All" would otherwise
 * silently disable every op://-backed credential for the remainder of the TUI
 * session, with no indication and no way back. A long-lived host calls this when
 * the user starts a NEW explicit 1Password action — that action is the retraction.
 *
 * Only the env flag is latched, so only the env flag is cleared: a denied
 * `createClient` evicts itself from `sdkClientCache` (see
 * `defaultSdkClientFactory`), so there is no poisoned client left to reset.
 */
export function clearOpSkip(): boolean {
  if (!opSkipLatchedByPrompt) return false;
  opSkipLatchedByPrompt = false;
  delete process.env.CLAUDISH_DISABLE_OP;
  return true;
}

/**
 * Run an SDK operation SERIALIZED (never concurrent with another SDK op) and,
 * on a TRANSIENT IPC error, evict the client cache (fresh desktop handshake),
 * pause briefly, and retry — up to 2 retries. Non-transient errors (auth, not
 * found, bad ref) propagate immediately. Serialization is the primary -4 fix;
 * the cache-reset + backoff retries handle a genuinely transient blip.
 *
 * `label` names the op in the startup trace (e.g. "tui:load-fields"). Each
 * attempt records its own queued span ({ attempt, waitMs, execMs }); when the
 * loop retried, the LAST attempt's span additionally gets
 * { attempts, retried, cacheReset } so a retry storm is visible in the metrics.
 */
export async function withSdkRetry<T>(op: () => Promise<T>, label = "op:sdk-op"): Promise<T> {
  // OUTER loop: locked-screen denial recovery. Wrapping (rather than folding
  // into the transient loop) keeps the two concerns separate — the inner loop
  // still owns millisecond-scale IPC blips, while this one owns the
  // human-scale "go unlock your Mac" wait. Every non-locked-denial error
  // propagates from the inner loop completely unchanged.
  for (let round = 1; ; round++) {
    try {
      return await withSdkTransientRetry(op, label);
    } catch (err) {
      // Re-classified every round: the user may unlock the Mac and leave
      // 1Password itself locked, which turns a "screen" round into an "app"
      // round. Pinning the cause once would then wait on a lock that already
      // cleared while the real blocker stayed put.
      const cause = classifyLockedDenial(err);
      if (round > LOCK_RETRY_ROUNDS || cause === null) throw err;
      const choice = await countdownForUnlock(round, LOCK_RETRY_ROUNDS, cause);
      if (choice === "skip") {
        // Honour "stop asking" for the WHOLE run, not just this op. A bare model
        // name walks a routing chain, so one refusal otherwise buys the user
        // three more countdowns for the same run. `CLAUDISH_DISABLE_OP` is the
        // existing single-run kill switch (`hasOpSources` returns false), so the
        // decision is expressed in the vocabulary the rest of the code already
        // reads — no second flag to keep in sync.
        latchOpSkip();
        throw err;
      }
      if (choice === "cancel") throw err;
      // Fresh handshake for the retry — the denied client is spent.
      resetSdkClientCache();
    }
  }
}

/** The transient-IPC retry loop (see withSdkRetry for the full contract). */
async function withSdkTransientRetry<T>(op: () => Promise<T>, label: string): Promise<T> {
  const MAX_ATTEMPTS = 3;
  let lastErr: unknown;
  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
    try {
      // Each attempt runs exclusively — no other SDK call overlaps it.
      const result = await runSdkExclusive(op, label, { attempt });
      if (attempt > 1) addSpanMeta(label, { attempts: attempt, retried: true, cacheReset: true });
      return result;
    } catch (err) {
      lastErr = err;
      if (!isTransientSdkError(err) || attempt === MAX_ATTEMPTS) {
        if (attempt > 1) addSpanMeta(label, { attempts: attempt, retried: true, cacheReset: true });
        throw err;
      }
      // Transient: drop the (possibly poisoned) client + back off before retry.
      resetSdkClientCache();
      await sdkSleep(150 * attempt);
    }
  }
  throw lastErr;
}

/**
 * Determine whether SDK auth is available WITHOUT blocking on any interactive
 * prompt or shelling out. Returns the auth descriptor, or undefined if the SDK
 * cannot be used from env alone (callers then run the richer resolveSdkAuth).
 *
 * Priority:
 *  1. OP_SERVICE_ACCOUNT_TOKEN → service-account token auth.
 *  2. OP_ACCOUNT → DesktopAuth(accountName). Only used when no service-account
 *     token is present. We never prompt to discover an account name here.
 *
 * The richer resolution (config account + single-account auto-detect +
 * interactive picker) lives in resolveSdkAuth(), which index.ts callers invoke
 * and then thread the resulting auth into resolveSecrets/discoverItemFields/
 * readEnvironment via opts.auth.
 */
export function detectSdkAuth(env: NodeJS.ProcessEnv = process.env): SdkAuth | undefined {
  const token = env.OP_SERVICE_ACCOUNT_TOKEN?.trim();
  if (token) return { kind: "token", token };
  const account = env.OP_ACCOUNT?.trim();
  if (account) return { kind: "desktop", accountName: account };
  return undefined;
}

/** A 1Password account as reported by `op account list --format=json`. */
export interface AccountInfo {
  /** Account sign-in URL, e.g. `my-team.1password.com`. Unique per account. */
  url: string;
  /** Account email (may collide across two accounts). */
  email: string;
  /** Account UUID. */
  account_uuid: string;
  /** User ID. */
  user_id: string;
}

/**
 * Injectable account lister. Default shells out to the read-only
 * `op account list --format=json`. Returns the parsed accounts, or null when
 * `op` is absent / fails / returns unparseable output. NEVER touches a secret.
 */
export type OpAccountLister = () => AccountInfo[] | null;

/**
 * Ceiling on the optional read-only `op account list` probe.
 *
 * The spawn was previously unbounded, which made it a HANG, not a slow path:
 * `op` blocks while the desktop app is locked or its keychain is cold, and
 * `spawnSync` with no timeout waits forever. Measured on a healthy machine this
 * call still takes 7-13s, so "it's fast" was never a safe assumption.
 *
 * The probe is OPTIONAL and read-only: a null result falls through to the
 * actionable "set OP_ACCOUNT" message. So cutting a genuinely slow-but-working
 * `op` short costs a remediation hint the user can follow, while leaving it
 * unbounded costs an indefinite hang with no output at all. Bounded wins.
 *
 * `defaultScreenLockProbe` has carried `timeout: 2000` since it was written;
 * these two simply never got the same treatment. 5s rather than 2s because `op`
 * talks to the desktop app, which is legitimately slower than `ioreg`.
 */
const OP_PROBE_TIMEOUT_MS = 5000;

/** Default account lister: read-only `op account list --format=json`. */
export const defaultOpAccountLister: OpAccountLister = () => {
  try {
    // `--cache=false` FIRST, and it is load-bearing on macOS Tahoe.
    //
    // Without it `op` spawns `op daemon --background` for its caching layer.
    // Those daemons reach into ~/Library/Group Containers/2BUA8C4S2C.com.1password,
    // which Tahoe's TCC treats as "accessing data from another app" — so the user
    // gets a system permission dialog that has nothing to do with 1Password's own
    // approval prompt, attributed to their TERMINAL rather than to claudish. Worse,
    // the daemons can hang indefinitely, which is what the 5s ceiling above was
    // papering over.
    //
    // Measured here: 2.767s with the daemon, 0.786s without, and no daemon left
    // behind. We never wanted the cache — this is a read-only account enumeration
    // that runs at most once per process.
    //
    // Reported upstream as openclaw/openclaw#55459 (op 2.33.0, macOS Tahoe 26.3.1);
    // reproduced here on op 2.38.2-beta.01, macOS 26.6.
    const res = spawnSync("op", ["--cache=false", "account", "list", "--format=json"], {
      encoding: "utf-8",
      timeout: OP_PROBE_TIMEOUT_MS,
    });
    if (res.error || res.status !== 0) return null;
    const parsed = JSON.parse(res.stdout ?? "");
    if (!Array.isArray(parsed)) return null;
    const accounts: AccountInfo[] = [];
    for (const raw of parsed) {
      if (!raw || typeof raw !== "object") continue;
      const a = raw as Partial<AccountInfo>;
      if (typeof a.url !== "string") continue;
      accounts.push({
        url: a.url,
        email: typeof a.email === "string" ? a.email : "",
        account_uuid: typeof a.account_uuid === "string" ? a.account_uuid : "",
        user_id: typeof a.user_id === "string" ? a.user_id : "",
      });
    }
    return accounts;
  } catch {
    // `op` missing, non-JSON output, or any other failure → no accounts.
    return null;
  }
};

/**
 * The outcome of desktop-account resolution. Either a concrete account name to
 * use with DesktopAuth, an actionable error string, or a request for the caller
 * to run an interactive picker over the listed accounts (and save the choice).
 */
export type DesktopAccountResult =
  | { accountName: string }
  | { error: string }
  | { needsPicker: AccountInfo[] };

/**
 * Resolve the account name for SDK DesktopAuth WITHOUT building a client.
 *
 * Order:
 *  (a) OP_ACCOUNT env → use it (ephemeral per-run override).
 *  (b) opts.configAccount (onepasswordAccount from config) → use it.
 *  (c) opts.opAccountLister() (read-only `op account list`):
 *      - exactly 1 account → use its url (zero-config single-account).
 *      - multiple + interactive TTY → { needsPicker } (caller prompts + saves).
 *      - multiple + non-interactive, OR op absent → { error } (with the account
 *        list when available).
 *
 * This is SYNC: the lister is sync (spawnSync) and there's no SDK/async work.
 * index.ts orchestrates the interactive picker around it.
 */
export function resolveDesktopAccount(
  opts: {
    env?: NodeJS.ProcessEnv;
    configAccount?: string;
    interactive?: boolean;
    opAccountLister?: OpAccountLister;
  } = {}
): DesktopAccountResult {
  const env = opts.env ?? process.env;

  // (a) Explicit env override.
  //
  // realValue() drops an unexpanded `${OP_ACCOUNT}` — the literal string a host
  // passes through when the referenced shell variable is unset. This is not
  // hypothetical: the obvious way to configure an account for the MCP server is
  // `"OP_ACCOUNT": "${OP_ACCOUNT}"` in the plugin's .mcp.json, and Claude Code
  // hands that string over verbatim when the variable is missing. Taken at face
  // value it becomes a DesktopAuth account name that cannot exist, so the
  // handshake fails and retries — measured at 4 wasted handshakes, and 4
  // possible 1Password prompts, from one malformed value. Treating it as absent
  // lets resolution fall through to the config account and the `op` default,
  // which is what the user meant.
  const envAccount = realValue(env.OP_ACCOUNT)?.trim();
  if (envAccount) return { accountName: envAccount };

  // (b) Saved config account.
  const configAccount = opts.configAccount?.trim();
  if (configAccount) return { accountName: configAccount };

  // (c) Enumerate accounts (optional, read-only).
  const lister = opts.opAccountLister ?? defaultOpAccountLister;
  const accounts = lister();

  const remediation =
    "Set OP_ACCOUNT to your account URL (e.g. my-team.1password.com) or " +
    "`onepasswordAccount` in ~/.claudish/config.json.";

  if (!accounts || accounts.length === 0) {
    return {
      error: `Could not determine which 1Password account to use (no service-account token, and \`op account list\` is unavailable). ${remediation}`,
    };
  }

  if (accounts.length === 1) {
    return { accountName: accounts[0].url };
  }

  // Multiple accounts.
  if (opts.interactive) {
    return { needsPicker: accounts };
  }

  // (d) Several accounts, no TTY, nothing declared. This is genuinely ambiguous
  // and claudish says so rather than choosing.
  //
  // A previous version asked `op account get` here and used whatever it named.
  // That was wrong, and the reason is worth keeping: `op` has no concept of a
  // "default account". `op account get` reports `system_auth_latest_signin` from
  // ~/.config/op/config — the account you MOST RECENTLY AUTHENTICATED WITH. So
  // the binding moved whenever the user signed into some other account for
  // unrelated work, and claudish would silently start looking for its keys in a
  // different account: a miss, or worse a hit on a same-named key holding a
  // different value. A credential source must not drift as a side effect of
  // something you did elsewhere.
  //
  // The fix is to DECLARE the account (OP_ACCOUNT, or `onepasswordAccount` —
  // which the interactive picker writes for you), all checked above. An
  // undeclared multi-account machine is an error, not a coin flip.
  const listing = accounts.map((a) => `  - ${a.url}${a.email ? ` (${a.email})` : ""}`).join("\n");
  return {
    error: `Multiple 1Password accounts are available and none is configured, so claudish cannot tell which one holds your keys. ${remediation}\nAccounts:\n${listing}`,
  };
}

/**
 * Orchestrated SDK auth resolution (async, the entry point index.ts callers use).
 *
 * Order:
 *  1. OP_SERVICE_ACCOUNT_TOKEN → token auth (headless).
 *  2. OP_ACCOUNT → DesktopAuth.
 *  3. opts.configAccount (onepasswordAccount) → DesktopAuth.
 *  4. resolveDesktopAccount's lister branch:
 *     - single account → DesktopAuth(url).
 *     - multiple + interactive → opts.onNeedsPicker(accounts) picks one (and the
 *       caller saves it); if no picker is supplied, hard-fail with the listing.
 *     - multiple + non-interactive OR op absent → throw the actionable error.
 *
 * Throws buildAuthError(...) when no usable auth can be resolved.
 */
export async function resolveSdkAuth(
  opts: {
    env?: NodeJS.ProcessEnv;
    configAccount?: string;
    interactive?: boolean;
    opAccountLister?: OpAccountLister;
    /**
     * Invoked when multiple accounts exist in an interactive session. Returns
     * the chosen account URL (the caller is expected to persist it), or
     * undefined/null to abort. Async so the caller can prompt.
     */
    onNeedsPicker?: (accounts: AccountInfo[]) => Promise<string | undefined>;
  } = {}
): Promise<SdkAuth> {
  const env = opts.env ?? process.env;

  // 1. Service-account token wins.
  const token = env.OP_SERVICE_ACCOUNT_TOKEN?.trim();
  if (token) return { kind: "token", token };

  // 2–4. Desktop account resolution.
  const result = resolveDesktopAccount({
    env,
    configAccount: opts.configAccount,
    interactive: opts.interactive,
    opAccountLister: opts.opAccountLister,
  });

  if ("accountName" in result) {
    return { kind: "desktop", accountName: result.accountName };
  }

  if ("needsPicker" in result) {
    if (opts.onNeedsPicker) {
      const chosen = await opts.onNeedsPicker(result.needsPicker);
      if (chosen?.trim()) {
        return { kind: "desktop", accountName: chosen.trim() };
      }
    }
    // No picker supplied, or the user aborted — fall through to an error.
    const listing = result.needsPicker
      .map((a) => `  - ${a.url}${a.email ? ` (${a.email})` : ""}`)
      .join("\n");
    throw buildAuthError(
      `Multiple 1Password accounts are available but none was selected.\nAccounts:\n${listing}`
    );
  }

  // result.error
  throw buildAuthError(result.error);
}

/**
 * Acquire an authenticated SDK client. Resolves auth from opts.auth, or falls
 * back to env-only detectSdkAuth (token / OP_ACCOUNT). When no auth is available
 * hard-fails with an actionable error — there is NO `op` CLI fallback.
 *
 * `context` is woven into the error so the user knows which operation needed
 * auth (e.g. "1Password Environment 'env-1'").
 */
export async function acquireSdkClient(
  opts: { sdkFactory?: SdkClientFactory; auth?: SdkAuth; env?: NodeJS.ProcessEnv },
  context: string
): Promise<SdkClientLike> {
  const auth = opts.auth ?? detectSdkAuth(opts.env ?? process.env);
  if (!auth) {
    throw buildAuthError(
      `1Password SDK auth is required for ${context}, but neither OP_SERVICE_ACCOUNT_TOKEN nor a 1Password account (OP_ACCOUNT / onepasswordAccount config) is available.`
    );
  }
  // Startup-trace: every SDK client passes through here, so this is the single
  // point that knows the auth kind for the metrics line ("desktop" | "token").
  setStartupAuthKind(auth.kind);
  const sdkFactory = opts.sdkFactory ?? defaultSdkClientFactory;
  return sdkFactory(auth);
}

/**
 * Map the SDK's resolveAll() response (keyed by op:// reference) back into our
 * `{ envVarName: secret }` shape WITHOUT throwing: per-ref failures are
 * collected alongside the successes. `refs` is the original
 * `{ envVarName: "op://..." }` map so we can re-associate by reference string.
 */
function mapSdkResolveAllPartial(
  refs: Record<string, string>,
  response: {
    individualResponses: Record<string, { content?: { secret: string }; error?: unknown }>;
  }
): { resolved: Record<string, string>; failures: string[] } {
  const responses = response.individualResponses ?? {};
  const resolved: Record<string, string> = {};
  const failures: string[] = [];

  for (const [envVar, ref] of Object.entries(refs)) {
    const entry = responses[ref];
    if (entry?.content && typeof entry.content.secret === "string") {
      resolved[envVar] = entry.content.secret;
      continue;
    }
    if (entry?.error !== undefined) {
      failures.push(`${envVar} (${ref}): ${describeSdkError(entry.error)}`);
      continue;
    }
    failures.push(`${envVar} (${ref}): no value returned`);
  }

  return { resolved, failures };
}

/**
 * All-or-nothing wrapper over mapSdkResolveAllPartial: THROWS a combined error
 * if any requested ref failed to resolve or is missing from the response.
 * (Explicit single-ref callers want loud failure; the full-glob path uses the
 * partial variant instead — one broken field must not sink the whole item.)
 */
function mapSdkResolveAll(
  refs: Record<string, string>,
  response: {
    individualResponses: Record<string, { content?: { secret: string }; error?: unknown }>;
  }
): Record<string, string> {
  const { resolved, failures } = mapSdkResolveAllPartial(refs, response);
  if (failures.length > 0) {
    throw new Error(
      `1Password SDK could not resolve secret reference(s):\n  ${failures.join("\n  ")}`
    );
  }
  return resolved;
}

/** Best-effort stringification of an SDK ResolveReferenceError variant. */
function describeSdkError(error: unknown): string {
  if (error && typeof error === "object") {
    const e = error as { type?: unknown; message?: unknown };
    const type = typeof e.type === "string" ? e.type : undefined;
    const message = typeof e.message === "string" ? e.message : undefined;
    if (type && message) return `${type}: ${message}`;
    if (type) return type;
    if (message) return message;
  }
  return String(error);
}

/**
 * Batch-resolve `{ envVarName: "op://..." }` refs via the SDK in one call.
 *
 *  - Empty input → `{}` (no SDK touched).
 *  - Otherwise → acquireSdkClient → secrets.resolveAll → mapSdkResolveAll.
 *  - No SDK auth → hard-fail (no `op` CLI fallback).
 *
 * Async because the SDK is async.
 */
export async function resolveSecrets(
  refs: Record<string, string>,
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
  } = {}
): Promise<Record<string, string>> {
  const keys = Object.keys(refs);
  if (keys.length === 0) return {};

  const client = await acquireSdkClient(opts, "resolving 1Password secret reference(s)");
  const response = await traceSpan(
    "op:secrets.resolveAll",
    () => client.secrets.resolveAll(keys.map((k) => refs[k])),
    { refs: keys.length }
  );
  return mapSdkResolveAll(refs, response);
}

/**
 * Like resolveSecrets, but tolerant of INDIVIDUAL reference failures: the batch
 * result is `{ resolved, failures }` instead of all-or-nothing. Used by the
 * full-glob path (resolveGlobImportAll), where one unresolvable field — e.g. a
 * `tooManyMatchingFields` duplicate label inside a section — must not sink the
 * item's other keys. The whole-BATCH failures (no auth, SDK/IPC error) still
 * throw; only per-ref resolution errors are collected.
 */
export async function resolveSecretsPartial(
  refs: Record<string, string>,
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
  } = {}
): Promise<{ resolved: Record<string, string>; failures: string[] }> {
  const keys = Object.keys(refs);
  if (keys.length === 0) return { resolved: {}, failures: [] };

  const client = await acquireSdkClient(opts, "resolving 1Password secret reference(s)");
  const response = await traceSpan(
    "op:secrets.resolveAll",
    () => client.secrets.resolveAll(keys.map((k) => refs[k])),
    { refs: keys.length }
  );
  return mapSdkResolveAllPartial(refs, response);
}

/**
 * Read a named 1Password Environment via the SDK and return its variables as a
 * `{ name: value }` map.
 *
 * THROWS (caller hard-fails) when:
 *  - the environment id is empty/invalid (usage error — asserted by tests).
 *  - no SDK auth is available.
 *  - the SDK lacks the environments API (you're on the stable 0.4.0 SDK; install
 *    0.4.1-beta.1).
 *  - the environment resolves to no variables.
 */
export async function readEnvironment(
  environmentId: string,
  opts: {
    sdkFactory?: SdkClientFactory;
    auth?: SdkAuth;
    env?: NodeJS.ProcessEnv;
  } = {}
): Promise<Record<string, string>> {
  const id = (environmentId ?? "").trim();
  if (id === "") {
    throw new Error("1Password Environment ID is empty. Usage: --op-env <environmentID>");
  }

  const client = await acquireSdkClient(opts, `1Password Environment '${id}'`);

  if (!client.environments || typeof client.environments.getVariables !== "function") {
    throw new Error(
      "1Password Environments require @1password/sdk 0.4.1-beta.1 or later (the " +
        "stable 0.4.0 has no environments API). Install: " +
        "`bun add @1password/[email protected]`."
    );
  }

  const { variables } = await traceSpan("op:environments.getVariables", () =>
    client.environments.getVariables(id)
  );
  if (!Array.isArray(variables) || variables.length === 0) {
    throw new Error(
      `1Password Environment '${id}' resolved to no variables. Check that the Environment ID is correct and contains entries.`
    );
  }

  const out: Record<string, string> = {};
  for (const v of variables) {
    if (v && typeof v.name === "string") out[v.name] = typeof v.value === "string" ? v.value : "";
  }
  return out;
}