crosscheck-cli 0.0.63 → 0.0.65

package/dist/model-prefs.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Personal model-preference storage + sync. Works on ANY tier — standard
+ * or enterprise — unlike enterprise/policy.ts's org-wide provider policy.
+ * Set locally via `crosscheck models set <provider> <model>` (pins the
+ * max/primary model) and `crosscheck models fallback <provider> <model>`
+ * (greenlights a fallback), or from the browser at crosscheckagent.com/
+ * account/models; each side best-effort pushes to the other so either one
+ * reflects the current chain.
+ *
+ * Deliberately fails OPEN (falls back to whatever's cached locally, or no
+ * preference at all) rather than restrictive, unlike the enterprise policy
+ * cache — a preference is a self-serve convenience, not a security
+ * control, so a network hiccup here should never block a call that would
+ * otherwise work fine on the engine's own default.
+ */
+/**
+ * Keyed by CLI-canonical provider name (see key-format.ts's
+ * CANONICAL_PROVIDERS — "grok", not "xai"). Each value is an ORDERED
+ * chain of model ids: index 0 is the pinned max/primary model, the rest
+ * are greenlit fallbacks tried in order if the primary comes back with a
+ * model-access failure (see crosscheck-mcp's core/model-fallback.ts —
+ * this is the exact list that ends up on the wire as
+ * `<PROVIDER>_MODEL` (index 0) + `<PROVIDER>_MODEL_FALLBACKS` (the rest).
+ */
+export type ModelPreferences = Readonly<Record<string, readonly string[]>>;
+/**
+ * Conflicts are persisted rather than reported inline because they are
+ * detected during `serve`, which has no way to ask anything: stdout is the
+ * MCP JSON-RPC channel and there is no terminal attached. So the detection
+ * and the question happen in different places — recorded here, asked the next
+ * time the user runs an interactive command.
+ */
+export declare function writePendingConflicts(conflicts: readonly PrefConflict[]): void;
+export declare function readPendingConflicts(): PrefConflict[];
+export declare function clearPendingConflicts(): void;
+/** confer vs confer-super. Mirrors MODEL_MODES on the server. */
+export type ModelMode = "default" | "super";
+/** Mode-scoped preferences, as stored locally and returned by the server's
+ *  `modes` field. */
+export type ModeScopedPreferences = Readonly<Record<ModelMode, ModelPreferences>>;
+/**
+ * Who chose a given provider's chain.
+ *
+ * Without this the cache cannot tell "the user pinned this here" from "we
+ * cached what the server said last time", which makes a non-destructive sync
+ * impossible: every server change would look either like an update (and
+ * silently clobber a deliberate local pin) or like a conflict (and nag about
+ * values nobody chose).
+ */
+export type PrefOrigin = "local" | "server";
+export type OriginMap = Readonly<Record<ModelMode, Readonly<Record<string, PrefOrigin>>>>;
+/** A local pin that disagrees with the server. Kept — never overwritten —
+ *  and surfaced for the user to resolve when they're somewhere interactive. */
+export interface PrefConflict {
+    mode: ModelMode;
+    provider: string;
+    local: readonly string[];
+    server: readonly string[];
+}
+export declare function readLocalOrigins(): OriginMap;
+/**
+ * The chains that should actually apply for a mode.
+ *
+ * Super layers OVER default per provider rather than replacing it wholesale:
+ * a user who pinned Anthropic for super and left the rest alone keeps their
+ * normal choices for the rest, instead of silently losing them.
+ */
+export declare function effectiveForMode(prefs: ModeScopedPreferences, mode: ModelMode): ModelPreferences;
+export declare function readLocalModelPrefs(): ModelPreferences;
+/** The full mode-scoped cache. Fails open to empty, like everything else in
+ *  this module — a preference is a convenience, not a gate. */
+export declare function readLocalModelModes(): ModeScopedPreferences;
+/** Exported for the mutators below and for tests. */
+export declare function __markOrigin(mode: ModelMode, provider: string, origin: PrefOrigin): void;
+/** Replace one provider's chain in one mode, preserving everything else.
+ *  Used by conflict resolution, which needs to write a specific mode. */
+export declare function setChainForMode(mode: ModelMode, provider: string, chain: readonly string[], origin: PrefOrigin): void;
+/** Pins the max/primary model (chain position 0), keeping any existing
+ *  fallbacks for that provider unchanged. */
+export declare function setLocalModelPref(provider: string, model: string): ModelPreferences;
+/** Greenlights a fallback model — appended after the primary and any
+ *  earlier fallbacks, unless it's already in the chain. Setting a
+ *  fallback for a provider with no primary yet is fine; the fallback
+ *  chain still works once a primary is set (or the engine default acts
+ *  as the de-facto primary). */
+export declare function addLocalModelFallback(provider: string, model: string): ModelPreferences;
+/** Removes one model from a provider's fallback chain — the primary
+ *  (position 0) can be removed this way too, promoting the next entry. */
+export declare function removeLocalModelFallback(provider: string, model: string): ModelPreferences;
+/** Clears a provider's whole chain (primary + fallbacks). */
+export declare function unsetLocalModelPref(provider: string): ModelPreferences;
+/**
+ * Pull the server-stored preference chains and merge them into the local
+ * cache — server values win for keys it returns; existing local-only
+ * entries (not yet pushed, e.g. from an offline `models set`) are
+ * preserved. Any failure just returns whatever's already cached locally.
+ */
+export declare function syncModelPreferencesFromServer(jwt: string): Promise<ModelPreferences>;
+/** Best-effort push of one provider's whole chain to the server — a
+ *  failure here only means the browser page won't reflect it until the
+ *  next successful sync; the local change still takes effect immediately. */
+export declare function pushModelPreferenceToServer(jwt: string, provider: string, models: readonly string[]): Promise<boolean>;
+/** Best-effort removal of one provider's whole chain on the server. */
+export declare function deleteModelPreferenceOnServer(jwt: string, provider: string): Promise<boolean>;

package/dist/model-resolve.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared "what model actually gets called for this provider, and why"
+ * resolution — used both to build the env vars `mcp.ts` hands the spawned
+ * engine, and to render `crosscheck models list`/`doctor`'s display. Pure
+ * given its inputs (env, local prefs, policy), so it's fully testable
+ * without touching the filesystem or network.
+ */
+import { type ModelPolicy } from "./model-policy.js";
+/** CLI-canonical provider name -> the engine's `<PROVIDER>_MODEL` env var.
+ *  Mirrors mcp.ts's KEY_BINDINGS pairing (same providers, same env-var
+ *  prefixes, `_API_KEY` -> `_MODEL`) — kept here since both the env
+ *  injection (mcp.ts) and the CLI/doctor display need it. The engine
+ *  reads the matching `<...>_MODEL_FALLBACKS` (comma-separated) itself —
+ *  see crosscheck-mcp's providers/registry.ts. */
+export declare const MODEL_ENV_VARS: Readonly<Record<string, string>>;
+export type ModelSource = 
+/** An explicit `<PROVIDER>_MODEL` env var in the shell — always wins. */
+"env"
+/** A personal preference set via `crosscheck models set` or the browser. */
+ | "preference"
+/** The org admin's `pinned` fallback, used because the candidate (if
+ *  any) wasn't allowed. */
+ | "policy-pinned"
+/** The first policy-allowed model, used because there was no candidate
+ *  and no `pinned` fallback either. */
+ | "policy-fallback"
+/** Nothing set anywhere — the engine's own built-in default will run. */
+ | "default"
+/** A candidate existed (env var or preference) but enterprise policy
+ *  rejected it, and no pinned/fallback model could be found either. */
+ | "blocked";
+export type ResolvedModel = {
+    provider: string;
+    /** undefined means: don't set the env var, defer to the engine's own
+     *  default for this provider. */
+    model?: string;
+    source: ModelSource;
+    /** Ordered "greenlight" fallbacks for this provider — tried, in order,
+     *  by the engine only when `model` comes back with a model-access
+     *  failure. Layered: the user's own configured fallback chain first,
+     *  then (if an enterprise model policy restricts this provider to a
+     *  specific allow-list) any other allowed models not already in the
+     *  list, as an automatic safety net even for a user who set no
+     *  fallbacks themselves. Always excludes `model` itself. */
+    fallbackModels: readonly string[];
+};
+export declare function resolveModelForProvider(args: {
+    provider: string;
+    env: Readonly<Record<string, string | undefined>>;
+    localPrefs: Readonly<Record<string, readonly string[]>>;
+    modelPolicy?: ModelPolicy;
+}): ResolvedModel;
+/** Resolves every canonical provider, regardless of whether it has a key
+ *  configured — callers filter to "has a key" themselves (mcp.ts) or show
+ *  everything (models list, so a not-yet-configured provider's policy is
+ *  still visible). */
+export declare function resolveAllModels(args: {
+    env: Readonly<Record<string, string | undefined>>;
+    localPrefs: Readonly<Record<string, readonly string[]>>;
+    modelPolicy?: ModelPolicy;
+}): ResolvedModel[];

package/dist/models-cli.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `crosscheck models` — the terminal half of model selection (the other
+ * half is crosscheckagent.com/account/models and, for org-wide policy,
+ * /account/enterprise). "Pin your max model, greenlight fallbacks": `set`
+ * pins the primary; `fallback` adds/removes greenlit fallbacks tried, in
+ * order, only when the primary comes back with a model-access failure
+ * (never for any other kind of error — see crosscheck-mcp's core/model-
+ * fallback.ts). See model-resolve.ts for the actual precedence — this
+ * file is purely command plumbing over it.
+ */
+export declare function runModelsCommand(sub: string | undefined, rest: string[]): Promise<void>;

package/dist/onepassword/browser-flow.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Browser wizard for 1Password setup — same trust pattern as
+ * keys-browser-flow.ts: the CLI spins up a localhost HTTP server, opens a
+ * Crosscheck (XC)-served form, and the form POSTs the collected config
+ * directly back to loopback. No one has to hand-write
+ * ~/.crosscheck/1password.json.
+ *
+ * The page collects authMode + per-provider Vault/Item/Field (combined into
+ * an op://vault/item/field reference client-side) — never a secret value,
+ * just where to find one. What gets POSTed back is re-validated in full by
+ * config.ts's writeOnePasswordConfig() exactly as if it had been hand-typed
+ * into the file — the browser is a convenience, not a trust boundary.
+ *
+ * Security properties (mirrors captureKeysViaBrowser):
+ *   - State token (32 bytes urlsafe) bound at server-start.
+ *   - Loopback only — binds 127.0.0.1, never 0.0.0.0.
+ *   - CORS locked to the served page's origin.
+ *   - Server accepts exactly one valid POST; subsequent calls 410.
+ *   - 10-minute timeout; self-terminates after the value lands or expires.
+ */
+import type { AuthMode } from "./config.js";
+export type CapturedOnePasswordConfig = {
+    authMode: AuthMode;
+    mappings: Record<string, string>;
+};
+export declare function captureOnePasswordConfigViaBrowser(args: {
+    providers: string[];
+    /** Existing mappings (op:// references, never values) to pre-fill —
+     *  lets `keys setup --backend 1password` re-open the wizard to add or
+     *  edit providers without losing what's already configured. */
+    existing?: Record<string, string>;
+    existingAuthMode?: AuthMode;
+    pageBaseUrl?: string;
+    timeoutMs?: number;
+}): Promise<CapturedOnePasswordConfig>;

package/dist/onepassword/config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Loader for ~/.crosscheck/1password.json — the per-provider secret-reference
+ * mapping for the (opt-in, enterprise) 1Password backend.
+ *
+ * Deliberately self-contained: this does NOT import from keychain.ts. That's
+ * not an accident of convenience — it keeps this security checkpoint's blast
+ * radius to exactly the src/onepassword/ tree instead of coupling it to the
+ * existing file/keychain backend internals (which aren't exported anyway).
+ *
+ * User-scope only, always — this never looks at a project/repo-local path.
+ * A config file living in the current working directory could let a
+ * malicious repo silently remap "anthropic" to a different, more-privileged
+ * 1Password item the developer's own session happens to have access to, and
+ * crosscheck would dutifully resolve and inject it. That's a secret-
+ * substitution vector this loader refuses to open.
+ */
+export type AuthMode = "desktop" | "service-account";
+export type OnePasswordConfig = {
+    authMode: AuthMode;
+    /** provider name -> validated op:// reference */
+    mappings: Readonly<Record<string, string>>;
+};
+export type OnePasswordConfigError = "not-found" | "not-a-regular-file" | "insecure-permissions" | "invalid-json" | "missing-auth-mode" | "invalid-auth-mode" | "missing-mappings" | "unknown-provider" | "invalid-reference";
+export type LoadOnePasswordConfigResult = {
+    ok: true;
+    config: OnePasswordConfig;
+} | {
+    ok: false;
+    error: OnePasswordConfigError;
+    detail: string;
+};
+export declare function configFilePath(): string;
+export declare function loadOnePasswordConfig(): LoadOnePasswordConfigResult;
+export type WriteOnePasswordConfigError = "invalid-auth-mode" | "unknown-provider" | "invalid-reference";
+export type WriteOnePasswordConfigResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: WriteOnePasswordConfigError;
+    detail: string;
+};
+/**
+ * Validate + atomically write ~/.crosscheck/1password.json. Used by the
+ * browser wizard (browser-flow.ts) so whatever a page POSTs back is held to
+ * EXACTLY the same grammar/provider checks a hand-written file would face on
+ * load — the browser is a convenience, never a trust boundary. Rejects the
+ * WHOLE write on any invalid entry rather than silently dropping bad ones,
+ * since a partially-applied config is easy to miss.
+ */
+export declare function writeOnePasswordConfig(input: {
+    authMode: string;
+    mappings: Record<string, string>;
+}): WriteOnePasswordConfigResult;

package/dist/onepassword/op.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `op` CLI runner — the only place this backend ever executes anything.
+ * Security checkpoint (see docs/onepassword-security.md): argv construction,
+ * environment policy, timeouts/cleanup, output caps, and the error taxonomy
+ * all live here.
+ *
+ * Hard rules:
+ *   - spawn() only, never a shell. Fixed argv shape, no user-controlled flags.
+ *   - The reference is re-validated here even though config.ts already
+ *     validated it on load — defense in depth, not redundancy for its own
+ *     sake, since this is the last checkpoint before anything reaches argv.
+ *   - Resolved secret values, tokens, and full op:// references never reach
+ *     a log, an error message, or telemetry. Errors carry category +
+ *     remediation + provider-agnostic detail only.
+ *   - Fail closed: any ambiguity (unparseable version, unmatched stderr,
+ *     unexpected exit) becomes a generic "unknown" error, never a pass.
+ */
+import type { AuthMode } from "./config.js";
+export declare const MIN_OP_VERSION = "2.18.0";
+export type OpReadErrorKind = "not-installed" | "wrong-version" | "not-signed-in" | "token-missing" | "malformed-reference" | "access-denied" | "item-or-field-missing" | "empty-value" | "output-too-large" | "timeout" | "unknown";
+export type OpReadResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    error: OpReadErrorKind;
+    detail: string;
+};
+export type OpVersionCheckResult = {
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    error: "not-installed" | "wrong-version" | "unknown";
+    detail: string;
+};
+export type OpRunnerOptions = {
+    authMode: AuthMode;
+    /** Required when authMode === "service-account"; ignored otherwise. */
+    serviceAccountToken?: string;
+    /** Override the `op` binary — defaults to "op" resolved via PATH. Tests
+     *  point this at an absolute path to a fake binary. */
+    opBin?: string;
+};
+export declare function checkOpVersion(opts?: {
+    opBin?: string;
+}): Promise<OpVersionCheckResult>;
+/**
+ * Read one secret value from 1Password. Re-validates `refInput` itself
+ * (never trusts a caller's prior validation), never falls back to any other
+ * source on failure, and never lets a resolved value, token, or reference
+ * reach the returned error on the failure path.
+ */
+export declare function readOpSecret(refInput: string, opts: OpRunnerOptions): Promise<OpReadResult>;

package/dist/onepassword/reference.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Strict parser/validator for 1Password secret references (`op://vault/item/field`).
+ *
+ * v1 supports only the plain 3-segment form — no optional `section` segment.
+ * Keeping the grammar minimal keeps this file (and its test surface) small,
+ * which matters because it's the first of two defense-in-depth checkpoints
+ * against CWE-78: op.ts (PR 2) re-validates immediately before spawning `op`,
+ * but rejecting anything that isn't a clean `op://...` string here means a
+ * malformed/hostile config value never gets far enough to be a runner
+ * concern. Anything not starting with the literal "op://" prefix also can't
+ * be mistaken for a flag by `op`'s own argument parser, since it's always
+ * passed as a single argv element via execFile — never a shell.
+ */
+export type OpReference = string & {
+    readonly __brand: "OpReference";
+};
+export type OpReferenceError = "empty" | "too-long" | "control-characters" | "query-or-fragment" | "missing-prefix" | "wrong-segment-count" | "empty-segment" | "invalid-characters";
+export type ParseOpReferenceResult = {
+    ok: true;
+    ref: OpReference;
+    vault: string;
+    item: string;
+    field: string;
+} | {
+    ok: false;
+    error: OpReferenceError;
+    detail: string;
+};
+export declare function parseOpReference(input: string): ParseOpReferenceResult;

package/dist/onepassword/setup.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `crosscheck keys setup --backend 1password` — validates the config end to
+ * end BEFORE ever persisting the backend preference. Never writes anything
+ * to 1Password (the backend is read-only); a "test read" only ever proves
+ * connectivity — the value is discarded immediately, never printed, never
+ * stored.
+ */
+import { type AuthMode } from "./config.js";
+export type ProviderCheckResult = {
+    provider: string;
+    ok: boolean;
+    error?: string;
+};
+export type OnePasswordSetupResult = {
+    ok: true;
+    authMode: AuthMode;
+    providers: ProviderCheckResult[];
+} | {
+    ok: false;
+    stage: "config" | "op-version" | "no-providers-resolved";
+    detail: string;
+    providers?: ProviderCheckResult[];
+};
+/**
+ * Validate config → `op` version → test-read every mapped provider.
+ * Discloses provider NAMES only, never a full op:// reference — matching
+ * the same disclosure discipline as op.ts's error taxonomy. Never touches
+ * the persisted backend preference; the caller only does that after seeing
+ * `{ ok: true }`.
+ *
+ * "Success" here means at least one mapped provider resolved — not that
+ * every one did. A single bad item/field name is a per-provider config
+ * typo the user can fix later; it shouldn't block enabling the backend for
+ * every OTHER provider that already works. A systemic problem (op missing,
+ * wrong version, or every single provider failing — usually a signed-out
+ * or invalid-token case) DOES block, since persisting a backend where
+ * nothing works at all isn't useful and would just defer the failure to
+ * the next `crosscheck serve`.
+ */
+export declare function validateOnePasswordSetup(): Promise<OnePasswordSetupResult>;
+/**
+ * Orchestrates `crosscheck keys setup --backend 1password`: by default,
+ * opens a browser wizard to collect authMode + per-provider Vault/Item/Field
+ * (pre-filled with whatever's already configured, so re-running to add one
+ * more provider doesn't lose the rest) and writes the config — no one has
+ * to hand-edit ~/.crosscheck/1password.json. Pass `{ useFile: true }` (the
+ * CLI's `--file` flag) to skip the browser and just validate a config
+ * that's already been placed there some other way (dotfiles, CI
+ * provisioning, etc.). Either way, ends the same: validate, then (only on
+ * success) persist the preference and report what's usable.
+ */
+export declare function runOnePasswordKeysSetup(opts?: {
+    useFile?: boolean;
+}): Promise<void>;

package/dist/open-browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Best-effort cross-platform browser opener. Failure is silent — callers
+ * always print the URL too, so a headless box just falls back to copy-paste.
+ * Kept dependency-light (no `open` package) on purpose.
+ */
+export declare function openBrowser(url: string): void;

package/dist/otel-setup.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Turn on Claude Code's OpenTelemetry metrics export and point it at
+ * Crosscheck, by merge-writing ~/.claude/settings.json.
+ *
+ * Why this file exists at all: the coding agent's own token usage is the
+ * larger share of what a feature costs, and Crosscheck cannot observe it from
+ * inside its own process. The only supported way to see it is Claude Code's
+ * OTel metrics export — which needs six environment variables set.
+ *
+ * Asking a developer to export six variables guarantees the feature is never
+ * used correctly, so the CLI writes them, exactly the way it already writes
+ * MCP registration. The user runs one command and types nothing.
+ *
+ * PRIVACY: metrics only. `OTEL_LOGS_EXPORTER` is explicitly pinned to "none",
+ * because Claude Code's *log* export can carry prompt content while its
+ * metrics are numeric by construction. That single line is what keeps the
+ * "server never sees prompt content" guarantee structural rather than a
+ * promise about what our parser chooses to read.
+ *
+ * Merge-write, never clobber: settings.json belongs to the user and may hold
+ * unrelated env, hooks, and permissions.
+ */
+/**
+ * Export interval, in ms. Claude Code's default is 60s, which means a metric
+ * point can span a minute — and any point straddling a branch switch has to be
+ * reported as ambiguous rather than assigned. Ten seconds shrinks that
+ * ambiguous band to roughly a percent of tokens. Lower is not obviously
+ * better: it multiplies request volume for precision nobody will read.
+ */
+export declare const EXPORT_INTERVAL_MS = 10000;
+export declare function claudeSettingsPath(): string;
+export type OtelEnv = Record<string, string>;
+/**
+ * The env block Claude Code needs.
+ *
+ * Auth is the seat's activation JWT in a header, NOT a per-event HMAC. The
+ * exporter is Claude Code itself — it has no access to the seat signing key
+ * and cannot be made to sign individual metric points. A bearer credential the
+ * server validates is the honest mechanism available here; the ingest route
+ * treats it accordingly and never trusts anything else in the payload.
+ */
+export declare function otelEnvFor(serverUrl: string, seatJwt: string): OtelEnv;
+/** Keys this module owns. Anything else in `env` is the user's and is left
+ *  untouched — including on disable, which removes only these. */
+export declare const MANAGED_KEYS: readonly ["CLAUDE_CODE_ENABLE_TELEMETRY", "OTEL_METRICS_EXPORTER", "OTEL_LOGS_EXPORTER", "OTEL_EXPORTER_OTLP_PROTOCOL", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_METRIC_EXPORT_INTERVAL"];
+type Settings = Record<string, unknown> & {
+    env?: Record<string, string>;
+};
+export declare function readSettings(file?: string): Settings;
+/**
+ * Merge the OTel env into settings.json.
+ *
+ * Returns `false` without writing when the file exists but doesn't parse:
+ * overwriting a developer's hooks and permissions to enable a cost dashboard
+ * is a spectacularly bad trade.
+ */
+export declare function enableOtel(serverUrl: string, seatJwt: string, file?: string): {
+    ok: boolean;
+    path: string;
+    reason?: string;
+};
+/** Remove only the keys we manage, leaving the rest of `env` alone. */
+export declare function disableOtel(file?: string): {
+    ok: boolean;
+    path: string;
+};
+/** Whether host-usage capture is currently wired up — used by `doctor`. */
+export declare function otelEnabled(file?: string): boolean;
+export {};

package/dist/pref-conflicts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolving model-preference conflicts, interactively, at a moment when
+ * there's actually a human present.
+ *
+ * The split matters: conflicts are DETECTED during `serve`, which cannot ask
+ * anything — stdout is the MCP JSON-RPC channel and there's no terminal. So
+ * serve records them and keeps the local pin, and the question is asked the
+ * next time someone runs an interactive command.
+ *
+ * The permission gate is the other half. An org's model policy can forbid the
+ * model a user pinned locally. Offering "keep yours" there would be offering
+ * something that cannot work — the engine would refuse it downstream — so a
+ * policy-blocked pin isn't presented as a choice. It's reported, and the
+ * server value is taken, because that is the only outcome available.
+ */
+import { type PrefConflict } from "./model-prefs.js";
+import type { ModelPolicy } from "./model-policy.js";
+export type ConflictOutcome = {
+    action: "none";
+} | {
+    action: "resolved";
+    kept: number;
+    updated: number;
+    policyForced: number;
+};
+/** Only ask where a person can answer. A prompt written to a pipe would hang
+ *  a script forever, which is a far worse failure than a stale preference. */
+export declare function canPrompt(): boolean;
+/** Is the locally pinned primary something org policy would refuse? If so,
+ *  "keep mine" isn't a real option and shouldn't be offered as one. */
+export declare function localPinAllowed(c: PrefConflict, policy?: ModelPolicy): boolean;
+/**
+ * Ask about any pending conflicts. No-op when there are none, when there's no
+ * terminal, or when the user declines to engage.
+ */
+export declare function resolvePendingConflicts(policy?: ModelPolicy): Promise<ConflictOutcome>;

package/dist/reconcile.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Self-healing reconciliation, run on every `serve`.
+ *
+ * THE PRINCIPLE: anything `install` does that is idempotent and
+ * non-interactive should also happen every time the engine starts. `install`
+ * is then genuinely first-run-only — activation, key capture, MCP
+ * registration — and a seat converges on the correct configuration by simply
+ * being used, rather than by someone remembering to re-run a command.
+ *
+ * Before this existed, two things only `install` did, so a seat that merely
+ * reconnected drifted:
+ *
+ *   1. The OTel host-telemetry config. Never refreshed — and worse, it embeds
+ *      the seat JWT, which expires after 7 days. Once it lapsed, host token
+ *      capture 401'd silently and forever, with nothing anywhere to say why.
+ *   2. Server-side model preferences. `syncModelPreferencesFromServer` was
+ *      reachable ONLY through `crosscheck models sync`, so a model chosen in
+ *      the browser reached a machine only if its owner happened to run that
+ *      command. The picker saved a choice that nothing collected.
+ *   3. Provider key METADATA (presence and last-4 only, never material).
+ *      Without it the browser knows nothing about any machine except the one
+ *      it is paired to, so a key that lapsed on another machine is invisible
+ *      until a panel silently comes back short a provider.
+ *
+ * Everything here is best-effort and fails OPEN. This runs on the critical
+ * path of an MCP connection: a slow or unreachable server must cost a stale
+ * preference, never a failed startup.
+ */
+export interface ReconcileReport {
+    /** "written" when we (re)wrote the OTel config, "current" when it already
+     *  matched, "skipped" when there was no JWT, "failed" with a reason. */
+    otel: "written" | "current" | "skipped" | "failed";
+    otelReason?: string;
+    /** "synced" when server preferences were pulled, "timeout" when the server
+     *  didn't answer in time, "skipped" without a JWT, "failed" otherwise. */
+    prefs: "synced" | "timeout" | "skipped" | "failed";
+    /**
+     * "dispatched" when a provider-metadata report was started, "skipped" when
+     * reporting is off or the seat has no usable JWT.
+     *
+     * Deliberately NOT the send's outcome. The report is fire-and-forget, so by
+     * the time it succeeds or fails this object has already been returned and
+     * read; a field claiming to hold the result would be reporting a value its
+     * reader can never have seen. Failures surface via CROSSCHECK_DEBUG.
+     */
+    keyStatus: "dispatched" | "skipped";
+}
+/**
+ * Bring this machine's configuration in line with the server and with what
+ * the current release expects. Never throws.
+ */
+export declare function reconcileSeat(args: {
+    jwt: string | null;
+    serverUrl: string;
+}): Promise<ReconcileReport>;
+/** One line to stderr when something was actually corrected. Silent on the
+ *  happy path — a message every single launch trains people to ignore it.
+ *  stderr, never stdout: stdout is the MCP JSON-RPC channel. */
+export declare function reportReconcile(r: ReconcileReport): void;

package/dist/signing.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Canonical event signing. MUST match the server's
+ * src/lib/crosscheck/crypto.ts byte-for-byte. Any drift breaks telemetry
+ * ingest because the server re-derives the seat HMAC key and recomputes
+ * the signature with the canonical body — if the strings differ, the
+ * signature won't verify.
+ *
+ * If the server adds a field to SignableEvent, this file must change in
+ * lockstep. Tests on both sides should sign + verify the same fixture to
+ * catch divergence.
+ */
+/**
+ * Order-stable, delimiter-safe canonical form of a usage event. Excludes
+ * the signature itself. Pipe-separated. Numbers stringified; cost is
+ * fixed at 6 decimals (toFixed(6)) to avoid floating-point drift.
+ */
+export type SignableEvent = {
+    eventId: string;
+    seatId: string;
+    orgId: string;
+    ts: string;
+    provider: string;
+    model: string;
+    pattern: string;
+    promptTokens: number;
+    completionTokens: number;
+    costUsdEstimate: number;
+    latencyMs: number;
+    status: string;
+    errorClass?: string;
+    /** Groups every call emitted by one tool invocation. */
+    runId?: string;
+    /** Role of this call inside the run (debate / synth / worker / …). */
+    purpose?: string;
+    /** Opaque git-context fingerprint for feature attribution. */
+    fingerprint?: string;
+};
+/**
+ * Canonical body, v2.
+ *
+ * The first 13 fields are FROZEN — seats already in the field sign exactly
+ * that string, and the server must keep verifying it. runId/purpose are
+ * appended only when at least one is present, so a legacy event yields the
+ * identical v1 string it always did.
+ */
+export declare function canonicalEventBody(e: SignableEvent): string;
+/** Sign a usage event with the per-seat HMAC key obtained at activation. */
+export declare function signEvent(seatSigningKey: string, e: SignableEvent): string;