crosscheck-cli 0.0.62 → 0.0.64

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;

package/dist/single-instance.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Single-instance guard for `crosscheck serve`.
+ *
+ * MCP hosts (Claude Code's `/mcp reconnect` in particular, as observed) don't
+ * always cleanly terminate the previous server child before spawning a new
+ * one — this leaves orphaned `crosscheck serve` processes running
+ * concurrently, each holding a stale in-memory snapshot (old code, old
+ * provider_allowlist, old keys). A fresh MCP connection can end up talking to
+ * whichever orphan still owns the stdio pipe, so "reconnect" silently does
+ * nothing.
+ *
+ * `claimSingleInstance()` records this process's PID in a lockfile and kills
+ * whatever PID was recorded there before, so every `serve` invocation is
+ * guaranteed to be the sole survivor for its own host.
+ *
+ * IMPORTANT: the lockfile is scoped by `process.ppid` (the parent that
+ * spawned this `serve` invocation — the MCP host itself: a terminal, a VS
+ * Code extension window, etc). Earlier this used one global `serve.pid` for
+ * the whole machine, which meant two *legitimately concurrent* hosts (e.g. a
+ * terminal Claude Code session and a VS Code Claude Code session running at
+ * the same time) would repeatedly SIGTERM each other's healthy connection —
+ * every reconnect in one window silently killed the other window's crosscheck
+ * MCP server. Scoping by ppid preserves the original orphan-cleanup behavior
+ * *within* one host's own reconnect flow, while leaving other hosts alone.
+ *
+ * `sweepOrphanedInstances()` is the complementary piece: it finds
+ * `crosscheck serve` / engine processes whose parent is no longer alive
+ * (true orphans — a host that crashed or was killed without cleaning up its
+ * child) and kills them, regardless of which host they belonged to. A
+ * process with a live parent is never touched by the sweep — that's always
+ * a legitimately running session, and ppid-scoped locking above is what
+ * governs it.
+ */
+export declare function pidFilePath(): string;
+/** Pre-fix global lockfile name. No longer written; cleaned up opportunistically. */
+export declare function legacyPidFilePath(): string;
+export declare function isAlive(pid: number): boolean;
+/**
+ * Best-effort check that `pid` actually looks like a crosscheck process,
+ * guarding against killing an unrelated process after PID reuse. Returns
+ * true when the check can't be performed at all (e.g. no `ps` on this
+ * platform) — better to proceed than to leave a genuinely stale lock from a
+ * crashed process stuck forever.
+ */
+export declare function looksLikeCrosscheckProcess(pid: number): boolean;
+/**
+ * Kill whatever PID the lockfile currently points at (if it's still alive
+ * and looks like a crosscheck process), then claim the lockfile for this
+ * process — recording the version now serving this host alongside the PID,
+ * so a stale-version incumbent is visible (in the log line here, and to
+ * `crosscheck doctor`) even when process-tree heuristics alone wouldn't
+ * flag it as an orphan. Call once, early, at the top of `serve`.
+ */
+export declare function claimSingleInstance(cliVersion: string, engineVersion: string): void;
+/** Best-effort cleanup on graceful exit — only removes the lockfile if it
+ *  still points at us (a newer instance may have already claimed it). */
+export declare function releaseSingleInstance(): void;
+/** Lockfile format is `<pid>\n<cliVersion>\n<engineVersion>\n` — the version
+ *  lines are a later addition, so a bare-PID file from an older `crosscheck`
+ *  (or mid-upgrade) still parses fine; the version fields just come back
+ *  null. */
+export interface RecordedInstance {
+    pid: number | null;
+    cliVersion: string | null;
+    engineVersion: string | null;
+}
+export declare function readRecordedInstance(file: string): RecordedInstance;
+export interface ProcessSnapshot {
+    pid: number;
+    ppid: number;
+    command: string;
+}
+/** Parse `ps -Ao pid=,ppid=,command=` output into structured rows. Exported
+ *  for testing; tolerant of extra whitespace and platforms where `command`
+ *  itself contains spaces. */
+export declare function parseProcessSnapshot(psOutput: string): ProcessSnapshot[];
+/**
+ * Pure decision function: given a process snapshot and a liveness check,
+ * return the pids that are genuine orphans — a crosscheck serve/engine
+ * process whose parent is gone (dead, or reparented to init/launchd, ppid
+ * 1). Never flags `selfPid`. Separated from the live `ps`/`kill` calls so
+ * the decision logic is unit-testable without spawning real processes.
+ */
+export declare function findOrphans(processes: ProcessSnapshot[], isAliveFn: (pid: number) => boolean, selfPid: number): number[];
+/**
+ * Find and kill any `crosscheck serve` / engine process on this machine
+ * whose parent process is no longer alive — true stragglers left behind by
+ * a host that crashed, was force-killed, or (pre-fix) lost the old
+ * machine-wide lock race. A process with a live parent is always a
+ * legitimate, currently-in-use session and is never touched here.
+ *
+ * Also opportunistically clears stale lockfiles (recorded pid no longer
+ * alive) and the pre-fix global lockfile, so `~/.crosscheck/` doesn't
+ * accumulate dead state forever. Best-effort throughout — failures here
+ * should never block `serve` from starting.
+ */
+export declare function sweepOrphanedInstances(): void;

package/dist/telemetry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Telemetry emitter. Signs each event with the per-seat HMAC key from
+ * activation and flushes batches to /api/crosscheck/telemetry on size or
+ * time threshold.
+ *
+ * Hard rule: nothing prompt-shaped goes in the event. The server's strict
+ * Zod schema rejects keys named prompt/messages/content/input/text/
+ * completion/response/output, so even an accidental log line never makes
+ * it past ingest. Don't add a "prompt_preview" field. Don't.
+ */
+export type EmitEventArgs = {
+    seatId: string;
+    orgId: string;
+    provider: "anthropic" | "openai" | "gemini" | "grok";
+    model: string;
+    pattern: "confer" | "debate" | "audit" | "plan" | "panel_pick" | "verify" | "critique" | "solve" | "other";
+    promptTokens: number;
+    completionTokens: number;
+    costUsdEstimate: number;
+    latencyMs: number;
+    status: "ok" | "error";
+    errorClass?: "rate_limit" | "auth" | "timeout" | "server" | "unknown";
+};
+export declare function emit(args: EmitEventArgs): Promise<void>;
+export declare function flush(): Promise<void>;

package/dist/update-check.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Non-blocking "newer version available" notice for `serve`.
+ *
+ * Fire-and-forget: queries the npm registry with a short timeout and writes
+ * ONE line to stderr if a newer crosscheck-cli is published. It never blocks
+ * startup, never writes to stdout (the MCP JSON-RPC channel), and never throws
+ * — offline / timeout / parse errors are swallowed.
+ */
+/** True when `latest` is a higher semver (major.minor.patch) than `current`. */
+export declare function isNewer(latest: string, current: string): boolean;
+/** Fetch a package's `latest` dist-tag version straight from the npm
+ *  registry, or null on any failure (offline, timeout, unpublished, bad
+ *  JSON). No throttling here — that's the caller's call (notifyIfOutdated
+ *  throttles via the shared cache; `crosscheck doctor` is an explicit,
+ *  on-demand check and always hits the registry fresh). */
+export declare function fetchLatestVersion(packageName: string): Promise<string | null>;
+export declare function notifyIfOutdated(current: string): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "crosscheck-cli",
-  "version": "0.0.62",
-  "description": "Crosscheck — multi-LLM orchestration MCP for the terminal. Single-machine activation, BYO upstream LLM keys, content-free telemetry. Installs into Claude Code in one command.",
+  "version": "0.0.64",
+  "description": "Crosscheck \u2014 multi-LLM orchestration MCP for the terminal. Single-machine activation, BYO upstream LLM keys, content-free telemetry. Installs into Claude Code in one command.",
   "license": "SEE LICENSE.md",
   "type": "module",
   "bin": {
@@ -27,12 +27,23 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "crosscheck-mcp": "0.2.23"
+    "crosscheck-mcp": "0.2.25"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js"
+    },
+    "./lib": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js"
+    },
+    "./package.json": "./package.json"
   }
 }