zk-credits 0.2.10 → 0.2.11

package/README.md

@@ -1,248 +1,84 @@
-> Release candidate `0.2.9` is prepared for owner publication. Registry commands
-> below apply after publication; the existing `0.2.8` lacks this flow.
-
 # zk-credits
 
-Loopback sidecar that attaches a hash-pinned BN254 Groth16 proof to each
-coding-agent LLM request through the experimental x402 `zk-prepaid` scheme.
-Built for the invite-only experimental Base Sepolia pilot. Product calls use
-founder-provisioned test credits and have no product payment step; the circuit
-is not independently audited. External research participants in slots A and C
-receive $25 for a 30-minute session regardless of setup success. That payment
-is not product revenue or willingness-to-pay evidence.
+API credits for Codex, Cline, and x402 agents. The local sidecar proves each
+spend and forwards your request to the gateway.
 
-```bash
-npm install --global zk-credits@0.2.9
-```
+Requires Node.js 20 or later. Runs on Base Sepolia.
 
-## Pinned pilot versions
+## Quick start
 
-The pilot supports exactly these versions. Do not substitute another, and do
-not mix versions between the sidecar, the adapter package, and the gateway:
+1. [Activate your credits](https://hazecredits.vercel.app) and download your activated credential.
+2. Install the package and configure a Base Sepolia RPC endpoint:
 
-| Package | Version |
-| --- | --- |
-| `zk-credits` (this sidecar) | `0.2.9` |
-| `@zk-credits/x402-zk-prepaid` (adapter) | `0.1.0` |
-| `@zk-credits/shared` | `0.1.0` |
-
-The pinned Base Sepolia trial version is `0.2.9`. It includes passwordless
-OS credential storage, the hash-pinned proving archive, public Base Sepolia RPC
-by default, a narrow Codex Responses bridge, and the request-aware x402 adapter.
-Setup validates the public chain witness and gateway-known root. No private
-GitHub repository access or recovery password is required for the new flow.
-
-Verify the shipped artifacts before your first prove. The package's
-`circuits/manifest.json` fixes the SHA-256 of the frozen
-`private_credit_spend.wasm`, `private_credit_spend.zkey`, and
-`verification_key_private_credit.json`; compute the digest of each delivered
-file and compare it to the manifest. A mismatch is a proof failure, and the
-sidecar refuses to prove rather than sending a payment. The founder compares
-the same digests against the delivered set before inviting you.
-
-## What one credit buys
-
-One credit buys one successfully committed response from the single service
-class `coding-deepseek-v4-flash-v1` (`deepseek/deepseek-v4-flash`). It is not
-an arbitrary API call, and the gateway enforces the class before it reserves
-the credit:
-
-- text messages, tool definitions, and tool calls, with one generated choice;
-- no provider streaming, images, files, audio, web search, model fallback,
-  client-selected routing, or unknown cost-affecting fields;
-- input capped at 128,000 UTF-8 byte units (counted conservatively, never below the
-  provider's token count), output at 4,000 tokens, request body at 256 KiB,
-  encrypted replay at 1 MiB, and upstream timeout at 120 seconds.
-
-The requested `model` field is ignored: the gateway always dispatches the
-class model, so an OpenAI-compatible client configured with any model name
-still receives the class. A rejected request consumes no credit.
-
-## First run
-
-1. Sign in at https://hazecredits.vercel.app and redeem your invite. Save and
-   reimport the passwordless recovery capsule, fund your pilot credential, then
-   download the activated credential. Anyone possessing these files can spend
-   their credits; keep them private.
-2. Import the activated file and validate setup:
-
-   ```bash
-   export ZK_CREDITS_CREDENTIAL_PATH="$HOME/Downloads/zk-credits-credential.json"
-   zk-credits setup codex
+   ```sh
+   npm install --global zk-credits
+   zk-credits config rpc
    ```
 
-   For your own x402 agent, use `zk-credits setup x402` instead. Setup installs
-   and verifies the packaged archive and artifact hashes, synchronizes public
-   Base events from the manifest-pinned bond and deployment block, and checks
-   the gateway-known root. Credentials enter OS secure storage: macOS Keychain,
-   Windows Credential Manager, or persistent Linux Secret Service. Storage
-   access approval may be needed; unavailable or denied storage fails closed.
-3. Review consent, choose your task, and run `zk-credits codex` or
-   `zk-credits x402-agent`. Subsequent launches use OS storage without a password
-   or import file. The activated download remains a private recovery backup.
-
-The RPC defaults to the launch endpoint baked into the package. If that endpoint is limited,
-run `zk-credits config rpc` and enter your own Base Sepolia endpoint in the hidden
-local prompt. Saved settings stay owner-only; `BASE_RPC_URL` takes precedence.
-Provider keys must not appear in chat or evidence. No gateway admin token is
-needed for operator setup.
-
-Existing encrypted exports require `zk-credits setup codex --legacy` (or
-`setup x402 --legacy`) and their original password in a hidden local prompt.
-A missing or altered proving artifact fails closed before payment creation.
-Setup and proving stay local; no supplied witness file is accepted for the
-manifest-pinned V2 deployment.
-
-The sidecar binds `127.0.0.1:3210` only. It does not modify `~/.cline` or
-`~/.codex`.
-
-## Supported route
-
-The pilot serves one bounded upstream spend path: non-streaming
-`POST /v1/chat/completions`, either through this sidecar or through an
-x402-native agent that explicitly registers the project `zk-prepaid` adapter.
-The sidecar also accepts Codex `POST /v1/responses` requests with text input
-and function tools, translates them to that bounded chat request, and converts
-the committed result into Responses SSE events. It rejects unsupported fields
-before starting a proof. Generic x402 clients, public facilitators, Bazaar,
-MCP, and the standard `exact` rail are unsupported; the sidecar never falls
-back to another rail.
-
-| Route | Auth | Purpose |
-| --- | --- | --- |
-| `GET /health` | none | Liveness for the local launcher |
-| `GET /v1/models` | local token | Codex model discovery |
-| `GET /metrics` | local token | Aggregate proof metrics (below) |
-| `POST /v1/chat/completions` | local token | The only proving and spend path |
-| `POST /v1/responses` | local token | Codex bridge to the bounded chat spend path |
-
-The chat route rejects streaming bodies (`stream`, `stream_options`) and a
-missing `model` with a `4xx` before any proof. The Responses route requires
-`stream: true`, text-only message/function-call input, and the known Codex
-metadata fields; it rejects images, unsupported tools, and unknown controls
-before any proof. Its upstream request is always `stream: false`. Anthropic
-`/v1/messages` and unknown paths return `404 unsupported_openai_path`. The
-sidecar never substitutes a model and never falls back to another rail.
-
-### Gateway responses and retries
-
-| Response | Meaning | What to do |
-| --- | --- | --- |
-| `402` | No usable authorization, or a stale or invalid one | Re-prove against the fresh challenge |
-| `409 claim_already_committed` | Your exact request already succeeded | Read `encryptedReplay` from the response, or fetch it from `POST /x402/replay`; do not re-prove |
-| `409 claim_commit_ambiguous` | The commit outcome is unknown | Retry the same request; never re-prove a different one |
-| `503 pilot_paused` | The operator paused the pilot | Wait. This is retryable, consumes no credit, and is not a proof failure |
-| `503 provider_spend_cap_exhausted` | The provider-spend cap paused the pilot | Wait for the operator to review. No credit was consumed |
-| `503 claim_store_unavailable` | Transient gateway fault | Retry with backoff |
-
-The gateway never asks you to re-prove for its own account. A `503` is
-retryable and free; a proof failure is local and never reaches the gateway.
-
-## Proof path
-
-- Local artifacts only, hash-pinned against the shipped manifest.
-- One prove at a time per sidecar process, in a terminable child-process
-  worker with a 10-second deadline. (snarkjs cannot run inside a Node
-  `worker_threads` worker: its `web-worker` polyfill re-enters itself there.)
-- Every proof is self-verified locally with the pinned verification key
-  before `PAYMENT-SIGNATURE` can be emitted, and its six public signals must
-  exactly match `[root, timestamp, domain, requestSignal, nullifier, share]`.
-- A failed attempt retries with the same slot, request signal, nonce,
-  response key, and gateway `issuedAt` while more than ten seconds remain in
-  the challenge window.
-- A slot is provisional during proving and recorded in the durable local
-  ledger (`$ZK_CREDITS_HOME/base-slots.json`) only after self-verification.
-  Proof misses, timeouts, hash failures, and verification failures release
-  it.
-
-## `GET /metrics`
-
-Aggregate only, authenticated with the same local token:
-
-```json
-{
-  "attempts": 12,
-  "successes": 11,
-  "failures": 1,
-  "retries": 1,
-  "failuresByCategory": { "timeout": 1, "artifact_hash_mismatch": 0, "...": 0 },
-  "hotProve": { "samples": 11, "p50Ms": 1180.4, "p95Ms": 1902.7 },
-  "updatedAt": "2026-09-20T14:00:00.000Z"
-}
-```
+3. Import your credential and connect Codex:
+
+   ```sh
+   ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup codex
+   zk-credits codex
+   ```
 
-The first prove in a process is the cold sample and is excluded from the hot
-percentiles. Proofs, public signals, nullifiers, credentials, requests, and
-any identifying label are never recorded or exposed.
+Setup stores your credential in OS secure storage. Keep your recovery file
+private: anyone with it can spend your credits.
 
 ## Commands
 
-```
-zk-credits cline [cline arguments...]
-zk-credits setup codex [--model <model>] [--legacy]
-zk-credits setup x402 [--legacy]
-zk-credits config rpc
-zk-credits codex [codex arguments...]
-zk-credits status
-zk-credits serve [--port <port>] [--internal-trial-one-proof]
-zk-credits x402-agent
-zk-credits founder-demo-agent
-zk-credits trial-registered-adapter
-eval "$(zk-credits env)"
+| Command | Purpose |
+| --- | --- |
+| `zk-credits setup codex` | Import a credential and configure Codex |
+| `zk-credits setup x402` | Prepare an x402 agent |
+| `zk-credits codex [args...]` | Start Codex with the local sidecar |
+| `zk-credits cline [args...]` | Start Cline with the local sidecar |
+| `zk-credits x402-agent` | Run the included x402 agent |
+| `zk-credits serve` | Run the sidecar in the foreground |
+| `zk-credits doctor` | Inspect the service, PID, setup, RPC source, and log location |
+| `zk-credits stop` | Stop the local sidecar |
+| `zk-credits status` | Check the Codex configuration and sidecar |
+| `zk-credits config rpc` | Save or change your Base Sepolia RPC endpoint |
+| `zk-credits --help` | Show command and troubleshooting guidance |
+
+`doctor` and `stop` are available in version 0.2.11. They work before setup.
+The default port is `3210`; set `ZK_CREDITS_SIDECAR_PORT` to select another port.
+Automatic startup logs are saved to `~/.zk-credits/sidecar.log`, or
+`$ZK_CREDITS_HOME/sidecar.log` when set.
+
+## Troubleshooting
+
+**Sidecar stopped or setup missing:** Run `zk-credits doctor`. If setup is
+missing, import your activated credential with the setup command above.
+Otherwise run `zk-credits serve` and read its output.
+
+**Port occupied or “Server is not running”:** `x402-agent` starts its own local
+server. Run `zk-credits stop` before switching from `serve` to `x402-agent`.
+For older versions, inspect the listener before stopping it:
+
+```sh
+lsof -nP -iTCP:3210 -sTCP:LISTEN
+ps -p <PID> -o pid,ppid,etime,command
+kill -TERM <PID>
 ```
 
-`serve --internal-trial-one-proof` is an opt-in maintainer mode for the
-internal Base Sepolia trial. During that process lifetime, one authenticated,
-valid spend request may reach the prepaid transport and the proof factory may
-attempt one proof. A later valid request receives HTTP 409 with
-`internal_trial_limit_reached`; ordinary `serve` behavior is unchanged without
-the flag.
-
-`trial-registered-adapter` is a maintainer-only internal trial command. It
-requires the locally recovered credential and pinned proving bundle, prompts
-for the credential password and gateway admin token without echo when they are
-not already configured, and requires an explicit confirmation before sending
-one billable request. It checks gateway readiness, authenticated admin status,
-Base root agreement, Codex profile/sidecar status, and remaining local slot
-capacity, then reports only the exchange phases and aggregate counter deltas.
-Run it only after recovery is complete and with the same `ZK_CREDITS_HOME`
-used by the sidecar; it registers `zk-prepaid` directly through the official
-x402 client adapter and reuses the durable slot ledger.
-
-Codex SDK:
-
-```ts
-import { buildCodexSdkOptions, buildCodexThreadOptions } from 'zk-credits/codex';
-```
+Check the PID and command to confirm it is your sidecar. For a foreground
+process, press Ctrl+C. `stop` authenticates the service and lets active requests
+finish before exit.
 
-`zk-credits/x402` exports `createLocalX402Agent` for an operator who is
-integrating the adapter into their own x402 agent. It loads the same local
-credential, pinned proof artifacts, public witness, proof engine, and slot
-ledger used by the sidecar. The request-aware client binds the actual method,
-URL, and body into each spend; its metrics endpoint exposes authenticated
-aggregate counters on loopback. See
-[`docs/onboarding/base-zk-credits-x402-agent.md`](../../docs/onboarding/base-zk-credits-x402-agent.md)
-for integration and measured-call steps. The included `zk-credits x402-agent`
-command is a small task-running starter for the founder demo and local
-rehearsal; external slot C uses their own agent.
-
-The credential secret is loaded from OS secure storage only into local memory. The sidecar cache
-contains public Base event leaves and never stores the secret, prompt, response,
-proof, account, or wallet.
-
-## Validation
-
-```bash
-npm test                                      # unit + fixture suites
-npm run build                                 # tsc + bundled CLI
-ZK_CREDITS_ARTIFACT_DIR="$PWD/circuits/artifacts" \
-  npx vitest run pinned-artifacts             # opt-in real fullProve + self-verify
-```
+**Base witness synchronization failed:** Run `zk-credits config rpc` and enter
+a Base Sepolia endpoint (chain ID `84532`). Stop and restart the sidecar, or
+retry setup if it failed. `BASE_RPC_URL` overrides the saved endpoint.
+A missing funded credential or rejected root can require activation checks;
+changing the RPC may not resolve it.
+
+## Clients and privacy
+
+Codex and Cline use the local OpenAI-compatible transport. Your own x402 agent
+must register the custom `zk-prepaid` adapter; generic x402 clients do not
+support this scheme automatically. See the [x402 integration guide](https://github.com/mangekyou-labs/haze-api/blob/main/docs/onboarding/base-zk-credits-x402-agent.md).
 
-The opt-in artifact test needs an installed bundle and the built
-`dist/proof-child.js`. CI stays deterministic through injected worker and
-crypto fixtures; the default suites stay green with no bundle installed.
+Your credential stays on your device. Proofs are sent to authorize each spend. The gateway and model provider receive request content and
+can observe traffic metadata. This does not hide your IP address.
 
-Base Sepolia only. The circuit is experimental and not independently audited.
-Development proving material is not suitable for mainnet; the repository's
-release gates require an audited production circuit and ceremony.
+Base Sepolia test credits only. The circuit is not independently audited.

package/dist/cli.js

@@ -15,6 +15,7 @@ import { createZkPrepaidLifecycleMetrics } from '@zk-credits/x402-zk-prepaid';
 import { BaseSlotLedger } from './slot-ledger.js';
 import { nativeCredentialStore, importCredentialPath, readStoredCredential } from './credential-store.js';
 import { applyRpcConfig, checkBaseSepoliaRpc, writeRpcConfig, RPC_GUIDANCE, resolveBaseSepoliaRpc } from './rpc-config.js';
+import { diagnoseSidecar, stopSidecar } from './sidecar-diagnostics.js';
 import { runCliCommand } from './cli-runtime.js';
 import { createNodeSidecarLifecycle } from './node-sidecar-lifecycle.js';
 import { activateSidecarServer } from './server-startup.js';
@@ -145,6 +146,8 @@ function printHelp() {
   zk-credits setup [codex|x402] [--legacy] [--model <model>]
   zk-credits codex [codex arguments...]
   zk-credits status
+  zk-credits doctor
+  zk-credits stop
   zk-credits serve [--port <port>] [--internal-trial-one-proof]
   zk-credits x402-agent
   zk-credits founder-demo-agent
@@ -159,11 +162,23 @@ the request-aware x402 adapter and local proof engine. It requires explicit
 confirmation before one billable internal exchange; the task and response are
 displayed locally and never added to activation evidence.
 "zk-credits x402-agent" is a small task-running starter for the participant's
-own x402 agent loop. It asks for tasks locally and sends each through the same
+own x402 agent loop. It starts its own metrics server on the selected sidecar port;
+stop an existing sidecar before launching it. It asks for tasks locally and sends each through the same
 request-aware adapter and local proof engine; aggregate metrics stay on the
 loopback-only authenticated endpoint.
 "zk-credits serve --internal-trial-one-proof" limits this sidecar process to
 one authenticated, valid spend request and one local proof attempt.
+"zk-credits doctor" reports health, authenticated PID, setup and RPC configuration
+presence, and log location without starting a server or revealing secrets.
+"zk-credits stop" gracefully drains the authenticated sidecar. For older versions,
+inspect the listener with lsof -nP -iTCP:3210 -sTCP:LISTEN, verify its PID with
+ps -p <PID> -o pid,ppid,etime,command, then kill -TERM <PID>. Foreground: Ctrl+C.
+Use ZK_CREDITS_SIDECAR_PORT for doctor, stop, status and env with a custom port.
+If serve reports missing setup, run:
+  ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup
+If the sidecar is stopped after setup, run zk-credits serve.
+For RPC witness synchronization failures, run zk-credits config rpc and then
+zk-credits stop followed by zk-credits serve. BASE_RPC_URL overrides the saved RPC.
 Base Sepolia uses the launch endpoint baked into the package automatically. RPC endpoints
 are rate-limited; run "zk-credits config rpc" to use your own endpoint.
 Provider guide: https://docs.base.org/base-chain/node-operators/node-providers
@@ -182,7 +197,7 @@ async function loadBaseClientRuntime() {
     const witnessPath = process.env.ZK_CREDITS_WITNESS_PATH;
     const artifactDirectory = process.env.ZK_CREDITS_ARTIFACT_DIR;
     if (!artifactDirectory) {
-        throw new Error('Set ZK_CREDITS_ARTIFACT_DIR to the directory holding the installed pinned proving bundle');
+        throw new Error('Proving bundle is not configured. Run zk-credits setup first; use ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup for first import. Run zk-credits doctor to inspect setup.');
     }
     const baseRpcUrl = process.env.BASE_RPC_URL;
     const baseContractAddress = process.env.BASE_PRIVATE_CREDIT_BOND_ADDRESS;
@@ -581,6 +596,12 @@ async function serve(args) {
         prepaidClient: prepaid.client,
         internalTrialOneProof,
         metrics: () => ({ ...proofMetrics.snapshot(), exchange: exchangeMetrics.snapshot() }),
+        onShutdown: () => {
+            void shutdown().catch((error) => {
+                console.error(error instanceof Error ? error.message : 'Sidecar shutdown failed');
+                process.exitCode = 1;
+            });
+        },
     });
     let address;
     try {
@@ -595,20 +616,33 @@ async function serve(args) {
     }
     console.log(`ZK Credits sidecar listening on ${address}/v1`);
     console.log('Run eval "$(zk-credits env)" in the client shell.');
-    const shutdown = async () => {
-        await sidecar.close();
-        process.exit(0);
+    let shutdownPromise;
+    const shutdown = () => {
+        shutdownPromise ??= sidecar.close().then(() => { process.exit(0); });
+        return shutdownPromise;
     };
     process.once('SIGINT', () => { void shutdown(); });
     process.once('SIGTERM', () => { void shutdown(); });
 }
 async function main() {
     const args = process.argv.slice(2);
-    if (args[0] === '--help' || args[0] === '-h' || !args[0]) {
+    const localHelp = ['doctor', 'stop', 'status', 'serve', 'setup', 'config'].includes(args[0] ?? '')
+        && args.slice(1).some((arg) => arg === '--help' || arg === '-h');
+    if (args[0] === '--help' || args[0] === '-h' || !args[0] || localHelp) {
         printHelp();
         return;
     }
     const sidecarHome = stateDirectory();
+    if (args[0] === 'doctor' || args[0] === 'stop') {
+        if (args.length !== 1)
+            throw new Error(`Usage: zk-credits ${args[0]} (use ZK_CREDITS_SIDECAR_PORT to select a port)`);
+        const options = { baseUrl: loopbackBaseUrl(), stateDirectory: sidecarHome, write: (line) => console.log(line) };
+        if (args[0] === 'doctor')
+            await diagnoseSidecar(options);
+        else
+            await stopSidecar(options);
+        return;
+    }
     if (args[0] === 'config' && args[1] === 'rpc' && args.length === 2) {
         console.log(RPC_GUIDANCE);
         const rpc = await checkBaseSepoliaRpc(await readHiddenValue('Base Sepolia RPC URL (hidden): '));
@@ -717,6 +751,11 @@ async function main() {
         process.exitCode = exitCode;
 }
 void main().catch((error) => {
-    console.error(error instanceof Error ? error.message : 'zk-credits failed');
+    if (error?.code === 'EADDRINUSE') {
+        console.error('The local port is already occupied. Run zk-credits doctor to identify the listener. Stop the existing sidecar with zk-credits stop (older sidecars: inspect the PID before kill -TERM <PID>), then retry. x402-agent starts its own local metrics server and does not reuse serve.');
+    }
+    else {
+        console.error(error instanceof Error ? error.message : 'zk-credits failed');
+    }
     process.exitCode = 1;
 });

package/dist/credential-store.js

@@ -46,7 +46,7 @@ export async function importStoredCredential(file, store, legacyPassword) {
 export async function readStoredCredential(store) {
     const raw = await store.read();
     if (!raw)
-        throw new Error('No credential in OS storage. Download your activated credential and run zk-credits setup first.');
+        throw new Error('No credential in OS storage. Download your activated credential and run zk-credits setup first: ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup.');
     try {
         const saved = JSON.parse(raw);
         if (saved.version !== 1 || !saved.credential)

package/dist/local-x402-agent.js

@@ -165490,7 +165490,7 @@ function nativeCredentialStore(stateDirectory) {
 async function readStoredCredential(store) {
   const raw = await store.read();
   if (!raw)
-    throw new Error("No credential in OS storage. Download your activated credential and run zk-credits setup first.");
+    throw new Error("No credential in OS storage. Download your activated credential and run zk-credits setup first: ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup.");
   try {
     const saved = JSON.parse(raw);
     if (saved.version !== 1 || !saved.credential)
@@ -165518,7 +165518,7 @@ function resolveBaseSepoliaRpc(environment, legacyRpc) {
     throw new Error("Release RPC has not been baked. Set BASE_RPC_URL or build the release package.");
   return rpc;
 }
-var RPC_GUIDANCE = "The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
+var RPC_GUIDANCE = "The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. After changing the RPC, run zk-credits stop then zk-credits serve; retry setup if it has not completed. BASE_RPC_URL overrides the saved setting. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
 function validateRpcUrl(value) {
   try {
     const url = new URL(value.trim());
@@ -167311,6 +167311,23 @@ function createSidecarServer(options) {
       return;
     }
     const token = extractLocalToken(req);
+    if (req.method === "GET" && pathname === "/runtime" || req.method === "POST" && pathname === "/shutdown") {
+      if (token !== options.localToken) {
+        sendJson(res, 401, { error: "invalid_local_token" });
+        return;
+      }
+      if (pathname === "/runtime") {
+        sendJson(res, 200, { service: "zk-credits-sidecar", pid: process.pid });
+      } else if (options.onShutdown) {
+        res.once("finish", () => {
+          setImmediate(() => options.onShutdown());
+        });
+        sendJson(res, 202, { service: "zk-credits-sidecar", status: "stopping" });
+      } else {
+        sendJson(res, 404, { error: "shutdown_unavailable" });
+      }
+      return;
+    }
     if (req.method === "GET" && pathname === "/v1/models") {
       if (token !== options.localToken) {
         sendJson(res, 401, { error: "invalid_local_token" });
@@ -167409,6 +167426,10 @@ function createSidecarServer(options) {
         return;
       const activeServer = server;
       server = null;
+      if (!activeServer.listening) {
+        await Promise.all(inFlight);
+        return;
+      }
       await new Promise((resolve4, reject) => activeServer.close((error) => {
         if (error)
           reject(error);

package/dist/rpc-config.d.ts

@@ -1,6 +1,6 @@
 export declare const DEFAULT_BASE_SEPOLIA_RPC_URL = "__ZK_CREDITS_RELEASE_RPC_URL__";
 export declare function resolveBaseSepoliaRpc(environment: NodeJS.ProcessEnv, legacyRpc?: string): string;
-export declare const RPC_GUIDANCE = "The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
+export declare const RPC_GUIDANCE = "The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. After changing the RPC, run zk-credits stop then zk-credits serve; retry setup if it has not completed. BASE_RPC_URL overrides the saved setting. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
 export declare function validateRpcUrl(value: string): string;
 export declare function checkBaseSepoliaRpc(value: string, request?: typeof fetch): Promise<string>;
 export declare function readRpcConfig(directory: string): Promise<string | undefined>;

package/dist/rpc-config.js

@@ -8,7 +8,7 @@ export function resolveBaseSepoliaRpc(environment, legacyRpc) {
         throw new Error('Release RPC has not been baked. Set BASE_RPC_URL or build the release package.');
     return rpc;
 }
-export const RPC_GUIDANCE = 'The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. Providers: https://docs.base.org/base-chain/node-operators/node-providers .';
+export const RPC_GUIDANCE = 'The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. After changing the RPC, run zk-credits stop then zk-credits serve; retry setup if it has not completed. BASE_RPC_URL overrides the saved setting. Providers: https://docs.base.org/base-chain/node-operators/node-providers .';
 export function validateRpcUrl(value) {
     try {
         const url = new URL(value.trim());

package/dist/setup-config.js

@@ -201,7 +201,7 @@ async function resolveWitnessSource(options, saved) {
     const explicitPath = environment.ZK_CREDITS_WITNESS_PATH?.trim();
     if (explicitPath) {
         if (options.manifest.deployment) {
-            throw new Error('Base Sepolia V2 setup requires a witness synchronized from the pinned public Base events');
+            throw new Error('Base Sepolia V2 setup requires a witness synchronized from the pinned public Base events. Unset ZK_CREDITS_WITNESS_PATH, run zk-credits config rpc, and retry zk-credits setup');
         }
         const source = {
             kind: 'file',
@@ -239,7 +239,7 @@ async function resolveWitnessSource(options, saved) {
         }
     }
     if (options.manifest.deployment) {
-        throw new Error('Base Sepolia V2 setup requires BASE_RPC_URL to sync the pinned V2 bond from its deployment block');
+        throw new Error('Base Sepolia V2 setup requires BASE_RPC_URL to sync the pinned V2 bond from its deployment block. Run zk-credits config rpc, then retry zk-credits setup');
     }
     if (saved?.witness.kind === 'file') {
         try {

package/dist/sidecar-diagnostics.d.ts

@@ -0,0 +1,7 @@
+export interface DiagnosticOptions {
+    baseUrl: string;
+    stateDirectory: string;
+    write(line: string): void;
+}
+export declare function diagnoseSidecar(options: DiagnosticOptions): Promise<void>;
+export declare function stopSidecar(options: DiagnosticOptions): Promise<void>;

package/dist/sidecar-diagnostics.js

@@ -0,0 +1,103 @@
+import { join } from 'node:path';
+import { readLoopbackToken } from './sidecar-state.js';
+import { sidecarStatePaths } from './sidecar-config.js';
+import { readRpcConfig } from './rpc-config.js';
+import { readSetupConfig } from './setup-config.js';
+function origin(baseUrl) {
+    const url = new URL(baseUrl);
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port) {
+        throw new Error('Diagnostics require a 127.0.0.1 HTTP URL with an explicit port');
+    }
+    return url.origin;
+}
+async function health(baseUrl) {
+    try {
+        const response = await fetch(`${origin(baseUrl)}/health`, { signal: AbortSignal.timeout(1_000), redirect: 'error' });
+        const body = await response.json().catch(() => null);
+        return response.ok && body?.service === 'zk-credits-sidecar' && body.status === 'ok'
+            ? 'running' : 'unrelated listener';
+    }
+    catch (error) {
+        return error.cause?.code === 'ECONNREFUSED' ? 'stopped' : 'unreachable';
+    }
+}
+async function operatorRequest(options, path, method = 'GET') {
+    const token = await readLoopbackToken(sidecarStatePaths(options.stateDirectory).tokenPath);
+    return fetch(`${origin(options.baseUrl)}${path}`, {
+        method, headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(2_000), redirect: 'error',
+    });
+}
+export async function diagnoseSidecar(options) {
+    const { write, stateDirectory } = options;
+    const baseUrl = origin(options.baseUrl);
+    write(`Loopback URL: ${baseUrl}`);
+    write(`State directory: ${stateDirectory}`);
+    write(`Startup log (auto-launched sidecar): ${sidecarStatePaths(stateDirectory).logPath}`);
+    const state = await health(baseUrl);
+    write(`Sidecar: ${state}`);
+    if (state === 'running') {
+        try {
+            const response = await operatorRequest(options, '/runtime');
+            const body = await response.json();
+            if (!response.ok || body.service !== 'zk-credits-sidecar' || !Number.isSafeInteger(body.pid) || Number(body.pid) <= 0)
+                throw new Error();
+            write(`Sidecar PID: ${body.pid} (authenticated)`);
+        }
+        catch {
+            write('Sidecar PID: unavailable (older sidecar or missing/mismatched local token).');
+        }
+    }
+    try {
+        write(`Saved setup: ${await readSetupConfig(join(stateDirectory, 'config.json')) ? 'configured' : 'missing'}`);
+    }
+    catch {
+        write('Saved setup: invalid or unreadable; rerun zk-credits setup.');
+    }
+    write('OS credential access: not checked; doctor does not request access.');
+    try {
+        const configured = await readRpcConfig(stateDirectory);
+        write(`RPC source: ${process.env.BASE_RPC_URL?.trim() ? 'BASE_RPC_URL environment override' : configured ? 'saved custom RPC' : 'saved setup or release default'} (URL redacted)`);
+    }
+    catch {
+        write('RPC config: invalid or unreadable; run zk-credits config rpc.');
+    }
+    if (state === 'running')
+        write('Stop: zk-credits stop');
+    else if (state === 'stopped')
+        write('Start: zk-credits serve. If setup is missing, run zk-credits setup first.');
+    else
+        write('Inspect the listener before starting or stopping a process on this port.');
+    write('RPC sync failure: run zk-credits config rpc, then stop and restart the sidecar. BASE_RPC_URL overrides saved RPC.');
+    write(`Manual inspection: lsof -nP -iTCP:${new URL(baseUrl).port} -sTCP:LISTEN; inspect the PID with ps before kill -TERM <PID>.`);
+}
+export async function stopSidecar(options) {
+    const state = await health(origin(options.baseUrl));
+    if (state === 'stopped') {
+        options.write('Sidecar is already stopped.');
+        return;
+    }
+    if (state !== 'running')
+        throw new Error(`Sidecar is ${state}; refusing shutdown. Run zk-credits doctor to inspect the listener.`);
+    let response;
+    try {
+        response = await operatorRequest(options, '/shutdown', 'POST');
+    }
+    catch {
+        throw new Error('Could not authenticate or reach the running sidecar. Run zk-credits doctor; inspect its PID before stopping it manually.');
+    }
+    if (!response.ok) {
+        throw new Error('Sidecar refused shutdown (older sidecar or mismatched token). Run zk-credits doctor; use Ctrl+C for foreground serve, or inspect its PID before kill -TERM <PID>.');
+    }
+    const body = await response.json();
+    if (body.service !== 'zk-credits-sidecar' || body.status !== 'stopping')
+        throw new Error('Shutdown response was not recognized. Run zk-credits doctor.');
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        if (await health(options.baseUrl) === 'stopped') {
+            options.write('Sidecar listener stopped. Active requests may still be draining.');
+            return;
+        }
+    }
+    throw new Error('Shutdown requested; the sidecar may still be draining active requests. Run zk-credits doctor to check.');
+}

package/dist/sidecar-lifecycle.js

@@ -10,5 +10,5 @@ export async function ensureSidecarReady(dependencies, options = {}) {
         if (await dependencies.isHealthy())
             return dependencies.readToken();
     }
-    throw new Error(`ZK Credits sidecar did not become ready; inspect ${dependencies.logPath}`);
+    throw new Error(`ZK Credits sidecar did not become ready; inspect ${dependencies.logPath}. Run zk-credits doctor, then zk-credits serve in the foreground to see the startup error. Missing setup: run zk-credits setup. RPC witness sync failure: run zk-credits config rpc and retry.`);
 }

package/dist/sidecar.d.ts

@@ -13,6 +13,8 @@ export interface SidecarMetricsSnapshot extends BaseProofMetricsSnapshot {
 }
 export interface SidecarOptions {
     localToken: string;
+    /** Called after an authenticated shutdown response is sent. */
+    onShutdown?: () => void;
     gatewayBaseUrl: string;
     prepaidClient: PrepaidTransport;
     /** Limits this process to one authenticated, valid spend request for the internal trial. */

package/dist/sidecar.js

@@ -125,6 +125,23 @@ export function createSidecarServer(options) {
             return;
         }
         const token = extractLocalToken(req);
+        if ((req.method === 'GET' && pathname === '/runtime') || (req.method === 'POST' && pathname === '/shutdown')) {
+            if (token !== options.localToken) {
+                sendJson(res, 401, { error: 'invalid_local_token' });
+                return;
+            }
+            if (pathname === '/runtime') {
+                sendJson(res, 200, { service: 'zk-credits-sidecar', pid: process.pid });
+            }
+            else if (options.onShutdown) {
+                res.once('finish', () => { setImmediate(() => options.onShutdown()); });
+                sendJson(res, 202, { service: 'zk-credits-sidecar', status: 'stopping' });
+            }
+            else {
+                sendJson(res, 404, { error: 'shutdown_unavailable' });
+            }
+            return;
+        }
         if (req.method === 'GET' && pathname === '/v1/models') {
             if (token !== options.localToken) {
                 sendJson(res, 401, { error: 'invalid_local_token' });
@@ -226,6 +243,10 @@ export function createSidecarServer(options) {
                 return;
             const activeServer = server;
             server = null;
+            if (!activeServer.listening) {
+                await Promise.all(inFlight);
+                return;
+            }
             await new Promise((resolve, reject) => activeServer.close((error) => {
                 if (error)
                     reject(error);

package/dist/zk-credits.js

@@ -17045,7 +17045,7 @@ var require_buffer_list = __commonJS({
         }
       }, {
         key: "join",
-        value: function join10(s) {
+        value: function join11(s) {
           if (this.length === 0) return "";
           var p = this.head;
           var ret = "" + p.data;
@@ -119077,7 +119077,7 @@ var require_lib34 = __commonJS({
       };
     }
     // @__NO_SIDE_EFFECTS__
-    function join10(separator = "") {
+    function join11(separator = "") {
       astr("join", separator);
       return {
         encode: (from) => {
@@ -119293,15 +119293,15 @@ var require_lib34 = __commonJS({
       convertRadix2,
       radix,
       radix2,
-      join: join10,
+      join: join11,
       padding
     };
-    exports.base16 = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(4), /* @__PURE__ */ alphabet("0123456789ABCDEF"), /* @__PURE__ */ join10(""));
-    exports.base32 = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"), /* @__PURE__ */ padding(5), /* @__PURE__ */ join10(""));
-    exports.base32nopad = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"), /* @__PURE__ */ join10(""));
-    exports.base32hex = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("0123456789ABCDEFGHIJKLMNOPQRSTUV"), /* @__PURE__ */ padding(5), /* @__PURE__ */ join10(""));
-    exports.base32hexnopad = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("0123456789ABCDEFGHIJKLMNOPQRSTUV"), /* @__PURE__ */ join10(""));
-    exports.base32crockford = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("0123456789ABCDEFGHJKMNPQRSTVWXYZ"), /* @__PURE__ */ join10(""), /* @__PURE__ */ normalize((s) => s.toUpperCase().replace(/O/g, "0").replace(/[IL]/g, "1")));
+    exports.base16 = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(4), /* @__PURE__ */ alphabet("0123456789ABCDEF"), /* @__PURE__ */ join11(""));
+    exports.base32 = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"), /* @__PURE__ */ padding(5), /* @__PURE__ */ join11(""));
+    exports.base32nopad = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"), /* @__PURE__ */ join11(""));
+    exports.base32hex = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("0123456789ABCDEFGHIJKLMNOPQRSTUV"), /* @__PURE__ */ padding(5), /* @__PURE__ */ join11(""));
+    exports.base32hexnopad = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("0123456789ABCDEFGHIJKLMNOPQRSTUV"), /* @__PURE__ */ join11(""));
+    exports.base32crockford = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(5), /* @__PURE__ */ alphabet("0123456789ABCDEFGHJKMNPQRSTVWXYZ"), /* @__PURE__ */ join11(""), /* @__PURE__ */ normalize((s) => s.toUpperCase().replace(/O/g, "0").replace(/[IL]/g, "1")));
     var hasBase64Builtin = /* @__PURE__ */ (() => typeof Uint8Array.from([]).toBase64 === "function" && typeof Uint8Array.fromBase64 === "function")();
     var decodeBase64Builtin = (s, isUrl) => {
       astr("base64", s);
@@ -119319,8 +119319,8 @@ var require_lib34 = __commonJS({
       decode(s) {
         return decodeBase64Builtin(s, false);
       }
-    } : /* @__PURE__ */ chain(/* @__PURE__ */ radix2(6), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"), /* @__PURE__ */ padding(6), /* @__PURE__ */ join10(""));
-    exports.base64nopad = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(6), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"), /* @__PURE__ */ join10(""));
+    } : /* @__PURE__ */ chain(/* @__PURE__ */ radix2(6), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"), /* @__PURE__ */ padding(6), /* @__PURE__ */ join11(""));
+    exports.base64nopad = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(6), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"), /* @__PURE__ */ join11(""));
     exports.base64url = hasBase64Builtin ? {
       encode(b) {
         abytes(b);
@@ -119329,9 +119329,9 @@ var require_lib34 = __commonJS({
       decode(s) {
         return decodeBase64Builtin(s, true);
       }
-    } : /* @__PURE__ */ chain(/* @__PURE__ */ radix2(6), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"), /* @__PURE__ */ padding(6), /* @__PURE__ */ join10(""));
-    exports.base64urlnopad = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(6), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"), /* @__PURE__ */ join10(""));
-    var genBase58 = /* @__NO_SIDE_EFFECTS__ */ (abc) => /* @__PURE__ */ chain(/* @__PURE__ */ radix(58), /* @__PURE__ */ alphabet(abc), /* @__PURE__ */ join10(""));
+    } : /* @__PURE__ */ chain(/* @__PURE__ */ radix2(6), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"), /* @__PURE__ */ padding(6), /* @__PURE__ */ join11(""));
+    exports.base64urlnopad = /* @__PURE__ */ chain(/* @__PURE__ */ radix2(6), /* @__PURE__ */ alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"), /* @__PURE__ */ join11(""));
+    var genBase58 = /* @__NO_SIDE_EFFECTS__ */ (abc) => /* @__PURE__ */ chain(/* @__PURE__ */ radix(58), /* @__PURE__ */ alphabet(abc), /* @__PURE__ */ join11(""));
     exports.base58 = /* @__PURE__ */ genBase58("123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz");
     exports.base58flickr = /* @__PURE__ */ genBase58("123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ");
     exports.base58xrp = /* @__PURE__ */ genBase58("rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz");
@@ -119363,7 +119363,7 @@ var require_lib34 = __commonJS({
     var createBase58check = (sha256) => /* @__PURE__ */ chain(checksum(4, (data) => sha256(sha256(data))), exports.base58);
     exports.createBase58check = createBase58check;
     exports.base58check = exports.createBase58check;
-    var BECH_ALPHABET = /* @__PURE__ */ chain(/* @__PURE__ */ alphabet("qpzry9x8gf2tvdw0s3jn54khce6mua7l"), /* @__PURE__ */ join10(""));
+    var BECH_ALPHABET = /* @__PURE__ */ chain(/* @__PURE__ */ alphabet("qpzry9x8gf2tvdw0s3jn54khce6mua7l"), /* @__PURE__ */ join11(""));
     var POLYMOD_GENERATORS = [996825010, 642813549, 513874426, 1027748829, 705979059];
     function bech32Polymod(pre) {
       const b = pre >> 25;
@@ -119472,7 +119472,7 @@ var require_lib34 = __commonJS({
         return Uint8Array.fromHex(s);
       }
     };
-    exports.hex = hasHexBuiltin ? hexBuiltin : /* @__PURE__ */ chain(/* @__PURE__ */ radix2(4), /* @__PURE__ */ alphabet("0123456789abcdef"), /* @__PURE__ */ join10(""), /* @__PURE__ */ normalize((s) => {
+    exports.hex = hasHexBuiltin ? hexBuiltin : /* @__PURE__ */ chain(/* @__PURE__ */ radix2(4), /* @__PURE__ */ alphabet("0123456789abcdef"), /* @__PURE__ */ join11(""), /* @__PURE__ */ normalize((s) => {
       if (typeof s !== "string" || s.length % 2 !== 0)
         throw new TypeError(`hex.decode: expected string, got ${typeof s} with length ${s.length}`);
       return s.toLowerCase();
@@ -121711,7 +121711,7 @@ var require_Registration = __commonJS({
       };
     }
     function verify(options) {
-      const { attestation = "none", credential, origin, rpId, userVerification = "required" } = options;
+      const { attestation = "none", credential, origin: origin2, rpId, userVerification = "required" } = options;
       const clientDataJSONBytes = new Uint8Array(credential.clientDataJSON);
       const clientDataJSON = Bytes.toString(clientDataJSONBytes);
       const clientData = JSON.parse(clientDataJSON);
@@ -121726,9 +121726,9 @@ var require_Registration = __commonJS({
       })();
       if (!challengeResult)
         throw new VerifyError("Challenge mismatch");
-      const origins = Array.isArray(origin) ? origin : [origin];
+      const origins = Array.isArray(origin2) ? origin2 : [origin2];
       if (!origins.includes(clientData.origin))
-        throw new VerifyError(`Origin mismatch: expected ${JSON.stringify(origin)}, got "${clientData.origin}"`);
+        throw new VerifyError(`Origin mismatch: expected ${JSON.stringify(origin2)}, got "${clientData.origin}"`);
       const attestationObjectBytes = new Uint8Array(credential.attestationObject);
       const attestation_ = Cbor.decode(attestationObjectBytes);
       const authData = attestation_.authData;
@@ -121948,11 +121948,11 @@ var require_Authenticator = __commonJS({
       return (bytes[33] << 24 | bytes[34] << 16 | bytes[35] << 8 | bytes[36]) >>> 0;
     }
     function getClientDataJSON(options) {
-      const { challenge, crossOrigin = false, extraClientData, origin = window.location.origin, type = "webauthn.get" } = options;
+      const { challenge, crossOrigin = false, extraClientData, origin: origin2 = window.location.origin, type = "webauthn.get" } = options;
       return JSON.stringify({
         type,
         challenge: Base64.fromHex(challenge, { url: true, pad: false }),
-        origin,
+        origin: origin2,
         crossOrigin,
         ...extraClientData
       });
@@ -122056,7 +122056,7 @@ var require_Authentication = __commonJS({
       };
     }
     function getSignPayload(options) {
-      const { challenge, crossOrigin, extraClientData, flag, origin, rpId, signCount, userVerification = "required" } = options;
+      const { challenge, crossOrigin, extraClientData, flag, origin: origin2, rpId, signCount, userVerification = "required" } = options;
       const authenticatorData = (0, Authenticator_js_1.getAuthenticatorData)({
         flag,
         rpId,
@@ -122066,7 +122066,7 @@ var require_Authentication = __commonJS({
         challenge,
         crossOrigin,
         extraClientData,
-        origin
+        origin: origin2
       });
       const clientDataJSONHash = Hash.sha256(Hex.fromString(clientDataJSON));
       const challengeIndex = clientDataJSON.indexOf('"challenge"');
@@ -122180,7 +122180,7 @@ var require_Authentication = __commonJS({
     };
     exports.SignFailedError = SignFailedError;
     function verify(options) {
-      const { challenge, metadata, origin, publicKey, rpId, signature } = options;
+      const { challenge, metadata, origin: origin2, publicKey, rpId, signature } = options;
       const { authenticatorData, clientDataJSON, userVerificationRequired } = metadata;
       const authenticatorDataBytes = Bytes.fromHex(authenticatorData);
       if (authenticatorDataBytes.length < 37)
@@ -122203,8 +122203,8 @@ var require_Authentication = __commonJS({
         return false;
       if (!clientData.challenge || Hex.fromBytes(Base64.toBytes(clientData.challenge)) !== challenge)
         return false;
-      if (origin !== void 0) {
-        const origins = Array.isArray(origin) ? origin : [origin];
+      if (origin2 !== void 0) {
+        const origins = Array.isArray(origin2) ? origin2 : [origin2];
         if (!origins.includes(clientData.origin))
           return false;
       }
@@ -143664,7 +143664,7 @@ var require_Account = __commonJS({
       return fromRoot(parameters);
     }
     function fromHeadlessWebAuthn(privateKey, options) {
-      const { access, keyAuthorizationManager, rpId, origin, internal_version } = options;
+      const { access, keyAuthorizationManager, rpId, origin: origin2, internal_version } = options;
       const publicKey = P256.getPublicKey({ privateKey });
       return from({
         ...access ? { access, keyAuthorizationManager } : {},
@@ -143676,7 +143676,7 @@ var require_Account = __commonJS({
             ...options,
             challenge: hash,
             rpId,
-            origin
+            origin: origin2
           });
           const signature = P256.sign({
             payload,
@@ -165081,7 +165081,7 @@ var require_cjs2 = __commonJS({
 // dist/cli.js
 import { homedir as homedir2 } from "node:os";
 import { readFile as readFile10 } from "node:fs/promises";
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 // dist/codex-launcher.js
@@ -166122,7 +166122,7 @@ async function importStoredCredential(file, store, legacyPassword) {
 async function readStoredCredential(store) {
   const raw = await store.read();
   if (!raw)
-    throw new Error("No credential in OS storage. Download your activated credential and run zk-credits setup first.");
+    throw new Error("No credential in OS storage. Download your activated credential and run zk-credits setup first: ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup.");
   try {
     const saved = JSON.parse(raw);
     if (saved.version !== 1 || !saved.credential)
@@ -166160,7 +166160,7 @@ function resolveBaseSepoliaRpc(environment, legacyRpc) {
     throw new Error("Release RPC has not been baked. Set BASE_RPC_URL or build the release package.");
   return rpc;
 }
-var RPC_GUIDANCE = "The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
+var RPC_GUIDANCE = "The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. After changing the RPC, run zk-credits stop then zk-credits serve; retry setup if it has not completed. BASE_RPC_URL overrides the saved setting. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
 function validateRpcUrl(value) {
   try {
     const url = new URL(value.trim());
@@ -167440,7 +167440,7 @@ async function resolveWitnessSource(options, saved) {
   const explicitPath = environment.ZK_CREDITS_WITNESS_PATH?.trim();
   if (explicitPath) {
     if (options.manifest.deployment) {
-      throw new Error("Base Sepolia V2 setup requires a witness synchronized from the pinned public Base events");
+      throw new Error("Base Sepolia V2 setup requires a witness synchronized from the pinned public Base events. Unset ZK_CREDITS_WITNESS_PATH, run zk-credits config rpc, and retry zk-credits setup");
     }
     const source = {
       kind: "file",
@@ -167475,7 +167475,7 @@ async function resolveWitnessSource(options, saved) {
     }
   }
   if (options.manifest.deployment) {
-    throw new Error("Base Sepolia V2 setup requires BASE_RPC_URL to sync the pinned V2 bond from its deployment block");
+    throw new Error("Base Sepolia V2 setup requires BASE_RPC_URL to sync the pinned V2 bond from its deployment block. Run zk-credits config rpc, then retry zk-credits setup");
   }
   if (saved?.witness.kind === "file") {
     try {
@@ -168026,6 +168026,23 @@ function createSidecarServer(options) {
       return;
     }
     const token = extractLocalToken(req);
+    if (req.method === "GET" && pathname === "/runtime" || req.method === "POST" && pathname === "/shutdown") {
+      if (token !== options.localToken) {
+        sendJson(res, 401, { error: "invalid_local_token" });
+        return;
+      }
+      if (pathname === "/runtime") {
+        sendJson(res, 200, { service: "zk-credits-sidecar", pid: process.pid });
+      } else if (options.onShutdown) {
+        res.once("finish", () => {
+          setImmediate(() => options.onShutdown());
+        });
+        sendJson(res, 202, { service: "zk-credits-sidecar", status: "stopping" });
+      } else {
+        sendJson(res, 404, { error: "shutdown_unavailable" });
+      }
+      return;
+    }
     if (req.method === "GET" && pathname === "/v1/models") {
       if (token !== options.localToken) {
         sendJson(res, 401, { error: "invalid_local_token" });
@@ -168124,6 +168141,10 @@ function createSidecarServer(options) {
         return;
       const activeServer = server;
       server = null;
+      if (!activeServer.listening) {
+        await Promise.all(inFlight);
+        return;
+      }
       await new Promise((resolve5, reject) => activeServer.close((error) => {
         if (error)
           reject(error);
@@ -168267,6 +168288,103 @@ async function createLocalX402Agent(options = {}) {
 // dist/cli.js
 import { createZkPrepaidLifecycleMetrics as createZkPrepaidLifecycleMetrics2 } from "@zk-credits/x402-zk-prepaid";
 
+// dist/sidecar-diagnostics.js
+import { join as join9 } from "node:path";
+function origin(baseUrl) {
+  const url = new URL(baseUrl);
+  if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port) {
+    throw new Error("Diagnostics require a 127.0.0.1 HTTP URL with an explicit port");
+  }
+  return url.origin;
+}
+async function health(baseUrl) {
+  try {
+    const response = await fetch(`${origin(baseUrl)}/health`, { signal: AbortSignal.timeout(1e3), redirect: "error" });
+    const body = await response.json().catch(() => null);
+    return response.ok && body?.service === "zk-credits-sidecar" && body.status === "ok" ? "running" : "unrelated listener";
+  } catch (error) {
+    return error.cause?.code === "ECONNREFUSED" ? "stopped" : "unreachable";
+  }
+}
+async function operatorRequest(options, path, method = "GET") {
+  const token = await readLoopbackToken(sidecarStatePaths(options.stateDirectory).tokenPath);
+  return fetch(`${origin(options.baseUrl)}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}` },
+    signal: AbortSignal.timeout(2e3),
+    redirect: "error"
+  });
+}
+async function diagnoseSidecar(options) {
+  const { write, stateDirectory: stateDirectory2 } = options;
+  const baseUrl = origin(options.baseUrl);
+  write(`Loopback URL: ${baseUrl}`);
+  write(`State directory: ${stateDirectory2}`);
+  write(`Startup log (auto-launched sidecar): ${sidecarStatePaths(stateDirectory2).logPath}`);
+  const state = await health(baseUrl);
+  write(`Sidecar: ${state}`);
+  if (state === "running") {
+    try {
+      const response = await operatorRequest(options, "/runtime");
+      const body = await response.json();
+      if (!response.ok || body.service !== "zk-credits-sidecar" || !Number.isSafeInteger(body.pid) || Number(body.pid) <= 0)
+        throw new Error();
+      write(`Sidecar PID: ${body.pid} (authenticated)`);
+    } catch {
+      write("Sidecar PID: unavailable (older sidecar or missing/mismatched local token).");
+    }
+  }
+  try {
+    write(`Saved setup: ${await readSetupConfig(join9(stateDirectory2, "config.json")) ? "configured" : "missing"}`);
+  } catch {
+    write("Saved setup: invalid or unreadable; rerun zk-credits setup.");
+  }
+  write("OS credential access: not checked; doctor does not request access.");
+  try {
+    const configured = await readRpcConfig(stateDirectory2);
+    write(`RPC source: ${process.env.BASE_RPC_URL?.trim() ? "BASE_RPC_URL environment override" : configured ? "saved custom RPC" : "saved setup or release default"} (URL redacted)`);
+  } catch {
+    write("RPC config: invalid or unreadable; run zk-credits config rpc.");
+  }
+  if (state === "running")
+    write("Stop: zk-credits stop");
+  else if (state === "stopped")
+    write("Start: zk-credits serve. If setup is missing, run zk-credits setup first.");
+  else
+    write("Inspect the listener before starting or stopping a process on this port.");
+  write("RPC sync failure: run zk-credits config rpc, then stop and restart the sidecar. BASE_RPC_URL overrides saved RPC.");
+  write(`Manual inspection: lsof -nP -iTCP:${new URL(baseUrl).port} -sTCP:LISTEN; inspect the PID with ps before kill -TERM <PID>.`);
+}
+async function stopSidecar(options) {
+  const state = await health(origin(options.baseUrl));
+  if (state === "stopped") {
+    options.write("Sidecar is already stopped.");
+    return;
+  }
+  if (state !== "running")
+    throw new Error(`Sidecar is ${state}; refusing shutdown. Run zk-credits doctor to inspect the listener.`);
+  let response;
+  try {
+    response = await operatorRequest(options, "/shutdown", "POST");
+  } catch {
+    throw new Error("Could not authenticate or reach the running sidecar. Run zk-credits doctor; inspect its PID before stopping it manually.");
+  }
+  if (!response.ok) {
+    throw new Error("Sidecar refused shutdown (older sidecar or mismatched token). Run zk-credits doctor; use Ctrl+C for foreground serve, or inspect its PID before kill -TERM <PID>.");
+  }
+  const body = await response.json();
+  if (body.service !== "zk-credits-sidecar" || body.status !== "stopping")
+    throw new Error("Shutdown response was not recognized. Run zk-credits doctor.");
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    await new Promise((resolve5) => setTimeout(resolve5, 100));
+    if (await health(options.baseUrl) === "stopped") {
+      options.write("Sidecar listener stopped. Active requests may still be draining.");
+      return;
+    }
+  }
+  throw new Error("Shutdown requested; the sidecar may still be draining active requests. Run zk-credits doctor to check.");
+}
+
 // dist/cli-runtime.js
 function setupModel(args) {
   const options = args.slice(1).filter((arg) => arg !== "--legacy");
@@ -168442,7 +168560,7 @@ async function ensureSidecarReady(dependencies, options = {}) {
     if (await dependencies.isHealthy())
       return dependencies.readToken();
   }
-  throw new Error(`ZK Credits sidecar did not become ready; inspect ${dependencies.logPath}`);
+  throw new Error(`ZK Credits sidecar did not become ready; inspect ${dependencies.logPath}. Run zk-credits doctor, then zk-credits serve in the foreground to see the startup error. Missing setup: run zk-credits setup. RPC witness sync failure: run zk-credits config rpc and retry.`);
 }
 
 // dist/base-registered-trial.js
@@ -168605,10 +168723,10 @@ import { BASE_SEPOLIA_NETWORK as BASE_SEPOLIA_NETWORK3 } from "@zk-credits/x402-
 function isRecord5(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-async function requireGatewayKnownRoot(root, origin, fetcher = fetch) {
+async function requireGatewayKnownRoot(root, origin2, fetcher = fetch) {
   let response;
   try {
-    response = await fetcher(new URL("/v1/root-known", origin), {
+    response = await fetcher(new URL("/v1/root-known", origin2), {
       method: "POST",
       headers: { accept: "application/json", "content-type": "application/json" },
       body: JSON.stringify({ root }),
@@ -168692,10 +168810,10 @@ function evaluateGatewayReadiness(status, body, now = Date.now()) {
 var DEFAULT_GATEWAY_URL2 = "https://zk-credits-gateway.onrender.com";
 var DEFAULT_PORT2 = 3210;
 function stateDirectory() {
-  return process.env.ZK_CREDITS_HOME || join9(homedir2(), ".zk-credits");
+  return process.env.ZK_CREDITS_HOME || join10(homedir2(), ".zk-credits");
 }
 function setupConfigPath(directory = stateDirectory()) {
-  return join9(directory, "config.json");
+  return join10(directory, "config.json");
 }
 async function applySavedSetupConfig(environment, directory = stateDirectory()) {
   await applyRpcConfig(environment, directory);
@@ -168803,6 +168921,8 @@ function printHelp() {
   zk-credits setup [codex|x402] [--legacy] [--model <model>]
   zk-credits codex [codex arguments...]
   zk-credits status
+  zk-credits doctor
+  zk-credits stop
   zk-credits serve [--port <port>] [--internal-trial-one-proof]
   zk-credits x402-agent
   zk-credits founder-demo-agent
@@ -168817,11 +168937,23 @@ the request-aware x402 adapter and local proof engine. It requires explicit
 confirmation before one billable internal exchange; the task and response are
 displayed locally and never added to activation evidence.
 "zk-credits x402-agent" is a small task-running starter for the participant's
-own x402 agent loop. It asks for tasks locally and sends each through the same
+own x402 agent loop. It starts its own metrics server on the selected sidecar port;
+stop an existing sidecar before launching it. It asks for tasks locally and sends each through the same
 request-aware adapter and local proof engine; aggregate metrics stay on the
 loopback-only authenticated endpoint.
 "zk-credits serve --internal-trial-one-proof" limits this sidecar process to
 one authenticated, valid spend request and one local proof attempt.
+"zk-credits doctor" reports health, authenticated PID, setup and RPC configuration
+presence, and log location without starting a server or revealing secrets.
+"zk-credits stop" gracefully drains the authenticated sidecar. For older versions,
+inspect the listener with lsof -nP -iTCP:3210 -sTCP:LISTEN, verify its PID with
+ps -p <PID> -o pid,ppid,etime,command, then kill -TERM <PID>. Foreground: Ctrl+C.
+Use ZK_CREDITS_SIDECAR_PORT for doctor, stop, status and env with a custom port.
+If serve reports missing setup, run:
+  ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup
+If the sidecar is stopped after setup, run zk-credits serve.
+For RPC witness synchronization failures, run zk-credits config rpc and then
+zk-credits stop followed by zk-credits serve. BASE_RPC_URL overrides the saved RPC.
 Base Sepolia uses the launch endpoint baked into the package automatically. RPC endpoints
 are rate-limited; run "zk-credits config rpc" to use your own endpoint.
 Provider guide: https://docs.base.org/base-chain/node-operators/node-providers
@@ -168839,7 +168971,7 @@ async function loadBaseClientRuntime() {
   const witnessPath = process.env.ZK_CREDITS_WITNESS_PATH;
   const artifactDirectory = process.env.ZK_CREDITS_ARTIFACT_DIR;
   if (!artifactDirectory) {
-    throw new Error("Set ZK_CREDITS_ARTIFACT_DIR to the directory holding the installed pinned proving bundle");
+    throw new Error("Proving bundle is not configured. Run zk-credits setup first; use ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup for first import. Run zk-credits doctor to inspect setup.");
   }
   const baseRpcUrl = process.env.BASE_RPC_URL;
   const baseContractAddress = process.env.BASE_PRIVATE_CREDIT_BOND_ADDRESS;
@@ -168849,12 +168981,12 @@ async function loadBaseClientRuntime() {
     contractAddress: baseContractAddress,
     ...process.env.BASE_DEPLOYMENT_BLOCK && /^\d+$/u.test(process.env.BASE_DEPLOYMENT_BLOCK) ? { deploymentBlock: process.env.BASE_DEPLOYMENT_BLOCK } : {},
     ...process.env.BASE_CONFIRMATIONS && /^\d+$/u.test(process.env.BASE_CONFIRMATIONS) ? { confirmations: process.env.BASE_CONFIRMATIONS } : {}
-  }, join9(stateDirectory(), "base-event-sync.json")) : (() => {
+  }, join10(stateDirectory(), "base-event-sync.json")) : (() => {
     throw new Error("Set ZK_CREDITS_WITNESS_PATH or configure BASE_RPC_URL and BASE_PRIVATE_CREDIT_BOND_ADDRESS");
   })();
   const proofMetrics = createBaseProofMetrics();
   const exchangeMetrics = createZkPrepaidLifecycleMetrics2();
-  const slotLedger = await BaseSlotLedger.open({ path: join9(stateDirectory(), "base-slots.json") });
+  const slotLedger = await BaseSlotLedger.open({ path: join10(stateDirectory(), "base-slots.json") });
   const prove = await createPinnedBaseProofGenerator({ artifactDirectory, metrics: proofMetrics });
   validateBaseCreditWitness(await witnessProvider.witnessForCredential(credential));
   return { credential, witnessProvider, slotLedger, proofMetrics, exchangeMetrics, prove };
@@ -168885,11 +169017,11 @@ function safeCount(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : void 0;
 }
 function gatewayOrigin() {
-  const origin = new URL(process.env.ZK_CREDITS_GATEWAY_URL || DEFAULT_GATEWAY_URL2);
-  if (origin.protocol !== "https:" || origin.username || origin.password || origin.search || origin.hash || origin.pathname !== "/") {
+  const origin2 = new URL(process.env.ZK_CREDITS_GATEWAY_URL || DEFAULT_GATEWAY_URL2);
+  if (origin2.protocol !== "https:" || origin2.username || origin2.password || origin2.search || origin2.hash || origin2.pathname !== "/") {
     throw new Error("The internal trial requires a plain HTTPS gateway origin");
   }
-  return origin;
+  return origin2;
 }
 async function readGatewayJson(url, headers) {
   try {
@@ -168908,16 +169040,16 @@ async function readGatewayJson(url, headers) {
 async function requireGatewayKnownRoot2(root) {
   await requireGatewayKnownRoot(root, gatewayOrigin());
 }
-async function gatewayReadiness(origin) {
-  const response = await readGatewayJson(new URL("/ready", origin), { accept: "application/json" });
+async function gatewayReadiness(origin2) {
+  const response = await readGatewayJson(new URL("/ready", origin2), { accept: "application/json" });
   const gate = evaluateGatewayReadiness(response.status, response.body);
   return {
     status: response.status,
     ...gate
   };
 }
-async function gatewayTrialSnapshot(origin, token) {
-  const response = await readGatewayJson(new URL("/v1/admin/status", origin), {
+async function gatewayTrialSnapshot(origin2, token) {
+  const response = await readGatewayJson(new URL("/v1/admin/status", origin2), {
     accept: "application/json",
     authorization: `Bearer ${token}`
   });
@@ -169198,7 +169330,13 @@ async function serve(args) {
     gatewayBaseUrl,
     prepaidClient: prepaid.client,
     internalTrialOneProof,
-    metrics: () => ({ ...proofMetrics.snapshot(), exchange: exchangeMetrics.snapshot() })
+    metrics: () => ({ ...proofMetrics.snapshot(), exchange: exchangeMetrics.snapshot() }),
+    onShutdown: () => {
+      void shutdown().catch((error) => {
+        console.error(error instanceof Error ? error.message : "Sidecar shutdown failed");
+        process.exitCode = 1;
+      });
+    }
   });
   let address2;
   try {
@@ -169212,9 +169350,12 @@ async function serve(args) {
   }
   console.log(`ZK Credits sidecar listening on ${address2}/v1`);
   console.log('Run eval "$(zk-credits env)" in the client shell.');
-  const shutdown = async () => {
-    await sidecar.close();
-    process.exit(0);
+  let shutdownPromise;
+  const shutdown = () => {
+    shutdownPromise ??= sidecar.close().then(() => {
+      process.exit(0);
+    });
+    return shutdownPromise;
   };
   process.once("SIGINT", () => {
     void shutdown();
@@ -169225,11 +169366,22 @@ async function serve(args) {
 }
 async function main() {
   const args = process.argv.slice(2);
-  if (args[0] === "--help" || args[0] === "-h" || !args[0]) {
+  const localHelp = ["doctor", "stop", "status", "serve", "setup", "config"].includes(args[0] ?? "") && args.slice(1).some((arg) => arg === "--help" || arg === "-h");
+  if (args[0] === "--help" || args[0] === "-h" || !args[0] || localHelp) {
     printHelp();
     return;
   }
   const sidecarHome = stateDirectory();
+  if (args[0] === "doctor" || args[0] === "stop") {
+    if (args.length !== 1)
+      throw new Error(`Usage: zk-credits ${args[0]} (use ZK_CREDITS_SIDECAR_PORT to select a port)`);
+    const options = { baseUrl: loopbackBaseUrl(), stateDirectory: sidecarHome, write: (line) => console.log(line) };
+    if (args[0] === "doctor")
+      await diagnoseSidecar(options);
+    else
+      await stopSidecar(options);
+    return;
+  }
   if (args[0] === "config" && args[1] === "rpc" && args.length === 2) {
     console.log(RPC_GUIDANCE);
     const rpc = await checkBaseSepoliaRpc(await readHiddenValue("Base Sepolia RPC URL (hidden): "));
@@ -169297,7 +169449,7 @@ async function main() {
         configPath: setupConfigPath(sidecarHome),
         manifest,
         validateWitness: async (source) => {
-          const provider = await witnessProviderForSource2(source, join9(stateDirectory(), "base-event-sync.json"));
+          const provider = await witnessProviderForSource2(source, join10(stateDirectory(), "base-event-sync.json"));
           const witness = validateBaseCreditWitness(await provider.witnessForCredential(credential));
           if (manifest.deployment)
             await requireGatewayKnownRoot2(witness.root);
@@ -169338,6 +169490,10 @@ async function main() {
     process.exitCode = exitCode;
 }
 void main().catch((error) => {
-  console.error(error instanceof Error ? error.message : "zk-credits failed");
+  if (error?.code === "EADDRINUSE") {
+    console.error("The local port is already occupied. Run zk-credits doctor to identify the listener. Stop the existing sidecar with zk-credits stop (older sidecars: inspect the PID before kill -TERM <PID>), then retry. x402-agent starts its own local metrics server and does not reuse serve.");
+  } else {
+    console.error(error instanceof Error ? error.message : "zk-credits failed");
+  }
   process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zk-credits",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "Loopback x402 zk-prepaid transport for private Base API credits.",
   "homepage": "https://hazecredits.vercel.app",
   "repository": {