@atbash/sdk 0.10.6-dev.0 → 0.10.9-dev.0

package/dist/browser.d.mts

@@ -310,6 +310,12 @@ interface AtbashOptions {
     orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     failClosed?: boolean;
+    /**
+     * Verbose diagnostics. Off by default. When on, a failed judge call also
+     * logs the response body, which is the difference between "judge API failed"
+     * and knowing why it failed. Opt-in because that body can echo the action.
+     */
+    debug?: boolean;
     logger?: AtbashLogger;
 }
 /** Canonical decision returned by `auditToolCall`. */
@@ -350,6 +356,8 @@ interface FromConfigOptions {
     /** Default org name — see {@link AtbashOptions.orgName}. */
     orgName?: string;
     failClosed?: boolean;
+    /** See {@link AtbashOptions.debug}. */
+    debug?: boolean;
     logger?: AtbashLogger;
 }
 /** Options accepted by `judgeAction`. */
@@ -414,6 +422,7 @@ declare class Atbash {
     readonly failClosed: boolean;
     /** Org key learned from the last agent-exists check, for this agent only. */
     private _orgKeyFromChain;
+    private readonly debug;
     private readonly logger;
     private readonly http;
     /**
@@ -427,7 +436,20 @@ declare class Atbash {
      * server-side replay protection windows never expire it mid-session.
      */
     private _authBearer;
+    /** Guards `logEnvironmentOnce` — hosts construct several clients. */
+    private static environmentLogged;
     constructor(privkey: string, options?: AtbashOptions);
+    /**
+     * Say which environment this build talks to, once per process.
+     *
+     * The endpoint and both chain RIDs are compiled in, chosen by the npm tag,
+     * and no configuration repoints a released build. So installing the build
+     * for the wrong environment is invisible: the plugin loads, the hook fires,
+     * and every judge call fails because the agent does not exist on the chain
+     * this build targets. Organisation names are not unique across environments
+     * either, so an org resolving is not evidence the build is right.
+     */
+    private logEnvironmentOnce;
     /**
      * Construct from resolved config: explicit overrides → env vars → the
      * `~/.config/atbash/config.json` file (see userConfig.resolve). The private
@@ -470,6 +492,15 @@ declare class Atbash {
      * explicitly false.
      */
     auditToolCall(input: ToolCallInput): Promise<Decision>;
+    /**
+     * One exit for every judge failure.
+     *
+     * Status and reason go in the *message*, not only in the meta object: hosts
+     * print the message and drop the meta, which is why this read as a bare
+     * "judge API failed" while the judge was answering with a precise reason.
+     * The response body follows only under `debug`, since it can echo the action.
+     */
+    private failJudge;
     private fail;
     getJudgmentStatus(judgmentId: string, agentPubkey?: string): Promise<JudgmentStatus>;
     getToolCalls(maxCount: number): Promise<ToolCallRecord[]>;
@@ -545,7 +576,13 @@ declare class Atbash {
     private raiseIfError;
     /** Wrap a failed HTTP *response* (non-2xx / non-200) as an AtbashAPIError. */
     private httpError;
-    /** Wrap a *transport* failure (fetch threw, no response) as an AtbashAPIError. */
+    /**
+     * Wrap a transport failure (fetch threw, no response) as an AtbashAPIError.
+     *
+     * `HttpTransportError.kind` names the cause; the message is already
+     * human-readable. `debug` echoes the original exception so operators can
+     * cross-reference with node / undici logs when a class doesn't match.
+     */
     private transportError;
     private json;
     static generateKeypair(): KeyPair;
@@ -571,6 +608,43 @@ declare class SignatureVerificationError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Thin typed fetch wrapper.
+ *
+ * openapi-typescript emits types only (no runtime client), so this is the
+ * single hand-written transport — generic `get`/`post` over global `fetch`
+ * with a per-request timeout. The endpoint-specific request/response *shapes*
+ * are pulled from the generated `schema.ts` at the call sites in client.ts, so
+ * the wire contract still lives in spec/openapi.yaml. Methods return the raw
+ * `Response` so the caller can read the exact bytes the server signed before
+ * any decode (judge signature verification) — mirroring the Python surface's
+ * use of raw httpx (DECISIONS 2026-05-22).
+ */
+type QueryValue = string | number | boolean | undefined | null;
+declare class HttpClient {
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    constructor(baseUrl: string, timeoutMs: number);
+    buildUrl(path: string, query?: Record<string, QueryValue>): string;
+    get(path: string, query?: Record<string, QueryValue>, headers?: Record<string, string>): Promise<Response>;
+    post(path: string, body: unknown, headers?: Record<string, string>): Promise<Response>;
+    private fetch;
+}
+/**
+ * A transport failure the SDK can act on. Every real cause the platform surfaces
+ * lands as one of these — the message names the cause in plain language so a
+ * plugin can show it to a user without decoding httpx / fetch internals.
+ *
+ * `cause` preserves the original error for debug logging; consumers that want
+ * the raw exception (e.g. tests) read it there.
+ */
+declare class HttpTransportError extends Error {
+    readonly kind: "timeout" | "aborted" | "dns" | "connect_refused" | "connection_reset" | "unknown";
+    constructor(kind: HttpTransportError["kind"], message: string, options?: {
+        cause?: unknown;
+    });
+}
+
 /** Normalize wire shapes (verdict casing, status, pubkey) to canonical forms. */
 
 declare function normalizeVerdict(raw: unknown): Verdict;
@@ -585,6 +659,8 @@ interface AtbashUserConfig {
     blockchainRid?: string;
     provider?: string;
     providerModel?: string;
+    /** "1" / "true" turns on verbose diagnostics. See AtbashOptions.debug. */
+    debug?: string;
 }
 declare function getConfigDir(): string;
 declare function getConfigPath(): string;
@@ -595,6 +671,26 @@ declare function resolve(key: keyof AtbashUserConfig, flagValue?: string): strin
 declare function resolveKeyPath(input?: string): string;
 declare function loadAgentFromFile(keyPath?: string): AgentAuth;
 
+/**
+ * Accepted key filenames, in precedence order.
+ *
+ * `guard-client-key` stays first: it is the name every existing install
+ * already has, and changing which file wins would silently switch agent
+ * identity for anyone holding both. `atbash-client-key` is accepted because
+ * it is the name people actually create — the old one carries retired
+ * branding — and hitting ENOENT on a key you just wrote, from a plugin that
+ * still reports itself installed, is a miserable first run.
+ */
+declare const KEY_FILENAMES: readonly ["guard-client-key", "atbash-client-key"];
+/** Every path checked when no explicit key path is given, in order. */
+declare function keyPathCandidates(): string[];
+/**
+ * Pick the key path: an explicit input wins untouched; otherwise the first
+ * accepted filename that exists, falling back to the preferred name so the
+ * error names something recognisable when nothing is there.
+ */
+declare function chooseKeyPath(input: string | undefined, exists: (p: string) => boolean): string;
+
 /**
  * Canonical secret kinds reported by the Rust core in `SecretMatch.kind`.
  * Wire is permissive (modelled as a free string in {@link SecretMatch})
@@ -613,6 +709,26 @@ declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHe
     reason?: string;
 };
 
+/**
+ * The boot memory-sync failure line.
+ *
+ * Split out of `guard-manager.ts` so it can be asserted without constructing a
+ * guard manager, which needs the native addon. The message is the whole point
+ * of AT-304: hosts print the message and drop the structured meta, so a cause
+ * that lives only in meta never reaches the operator.
+ */
+/** Advice, not a diagnosis — appended only when the cause is unhelpful. */
+declare const BOOT_SYNC_HINT = "check the chain endpoint and orgName if the cause above does not explain it";
+/**
+ * Lead with the real cause.
+ *
+ * The previous wording named the chain endpoint and orgName as the things to
+ * check, which sent operators to verify configuration that was already correct
+ * while the actual cause (a node answering `404 Can't find blockchain with
+ * blockchainRID: …` for a chain it does not host) stayed hidden.
+ */
+declare function bootSyncFailureLine(cause: unknown): string;
+
 /** Derive the 32-byte AES key from an agent's secp256k1 privkey (hex). Deterministic — same privkey always yields the same key. */
 declare function deriveMemoryKey(privkey: string): Promise<Buffer>;
 /** Encrypt UTF-8 plaintext. `ciphertext` has the 16-byte GCM auth tag appended, matching the SDK's on-chain byte layout. */
@@ -1164,4 +1280,4 @@ declare function containsSecret(text: string): boolean;
 declare function createMemorySnapshot(entries: MemoryEntry[], takenAt: number): MemorySnapshot;
 declare function diffMemorySnapshots(before: MemorySnapshot, after: MemorySnapshot): MemoryDiffResult;
 
-export { type ActionType, type AgentAuth, type AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, type ChainOpts, type ClassifierToolContext, type ClassifierToolEvent, type ClassifyMemoryReadOptions, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_READ_TOOL_NAMES, DEFAULT_MEMORY_WRITE_TOOL_NAMES, type Decision, type DecisionVerdict, EciesDomain, type EncryptedMemory, type Envelope, type FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type HookDecision, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, MemoryGuardManager, type MemoryGuardManagerOptions, MemoryIntegrityError, type MemoryPointer, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OrgSubscription, PointerStore, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type SyncMemoryOptions, type SyncMemoryResult, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, buildAllowedJudgeHosts, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveMemory, getActiveMemoryId, getAllAgentMemory, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };
+export { type ActionType, type AgentAuth, type AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, BOOT_SYNC_HINT, type ChainOpts, type ClassifierToolContext, type ClassifierToolEvent, type ClassifyMemoryReadOptions, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_READ_TOOL_NAMES, DEFAULT_MEMORY_WRITE_TOOL_NAMES, type Decision, type DecisionVerdict, EciesDomain, type EncryptedMemory, type Envelope, type FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type HookDecision, HttpClient, HttpTransportError, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, KEY_FILENAMES, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, MemoryGuardManager, type MemoryGuardManagerOptions, MemoryIntegrityError, type MemoryPointer, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OrgSubscription, PointerStore, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type SyncMemoryOptions, type SyncMemoryResult, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, bootSyncFailureLine, buildAllowedJudgeHosts, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveMemory, getActiveMemoryId, getAllAgentMemory, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };

package/dist/browser.mjs

@@ -12126,7 +12126,7 @@ function requireBuffer_list() {
       }
     }, {
       key: "join",
-      value: function join2(s2) {
+      value: function join3(s2) {
         if (this.length === 0) return "";
         var p = this.head;
         var ret = "" + p.data;
@@ -16208,7 +16208,7 @@ function requireBufferList() {
         this.head = this.tail = null;
         this.length = 0;
       };
-      BufferList2.prototype.join = function join2(s2) {
+      BufferList2.prototype.join = function join3(s2) {
         if (this.length === 0) return "";
         var p = this.head;
         var ret = "" + p.data;
@@ -30372,7 +30372,7 @@ function requireBuffer() {
     }
   }
   buffer.EncoderBuffer = EncoderBuffer2;
-  EncoderBuffer2.prototype.join = function join2(out, offset) {
+  EncoderBuffer2.prototype.join = function join3(out, offset) {
     if (!out)
       out = new Buffer5(this.length);
     if (!offset)
@@ -43294,9 +43294,9 @@ var index = /* @__PURE__ */ getDefaultExportFromCjs(builtExports);
 
 // src-ts/browser/native.ts
 var { Buffer: Buffer3, gtx: pcgtx } = index;
-var ATBASH_ENDPOINT = "https://atbash.ai";
-var ATBASH_BLOCKCHAIN_RID = "0163241D9AF137638E63E48EFCDE15510F38C2426F7AD5DC726AF60351BF4DFE";
-var ATBASH_PRIVATE_BLOCKCHAIN_RID = "39FFD3557D0296CB2C57FDC6A3B8C024E95639CF4964DA08141AC20C6344D408";
+var ATBASH_ENDPOINT = "https://chromia-verified-ai-dev-two.vercel.app";
+var ATBASH_BLOCKCHAIN_RID = "02668C5218871F69A93CC0F7032DCFFE06EF0D35EF2F0B07A92A3D83A3F23A7D";
+var ATBASH_PRIVATE_BLOCKCHAIN_RID = "2603569AE8DC3F254323F719C8D4347BBA964E874E781291F8474236BE8B6493";
 var DEFAULT_CHROMIA_NODE_URLS_ARR = define_ATBASH_CHROMIA_NODE_URLS_default;
 var DEFAULT_PRIVATE_NODE_URLS_ARR = define_ATBASH_PRIVATE_NODE_URLS_default;
 var MERKLE_HASH_VERSION = 2;
@@ -44478,9 +44478,69 @@ var HttpClient = class {
     });
   }
   async fetch(url, init4) {
-    return fetch(url, { ...init4, signal: AbortSignal.timeout(this.timeoutMs) });
+    try {
+      return await fetch(url, {
+        ...init4,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      throw classifyTransportError(err, url, init4.method ?? "GET", this.timeoutMs);
+    }
   }
 };
+var HttpTransportError = class extends Error {
+  kind;
+  constructor(kind, message, options) {
+    super(message, options);
+    this.name = "HttpTransportError";
+    this.kind = kind;
+  }
+};
+function classifyTransportError(err, url, method, timeoutMs) {
+  const name2 = err instanceof Error ? err.name : "";
+  const cause = err instanceof Error ? err.cause : void 0;
+  const code2 = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : "";
+  if (name2 === "TimeoutError") {
+    return new HttpTransportError(
+      "timeout",
+      `${method} ${url} did not respond within ${timeoutMs} ms \u2014 the judge may be slow to boot or the LLM is under load; retry in a moment`,
+      { cause: err }
+    );
+  }
+  if (name2 === "AbortError") {
+    return new HttpTransportError(
+      "aborted",
+      `${method} ${url} was cancelled by the caller`,
+      { cause: err }
+    );
+  }
+  if (code2 === "ENOTFOUND" || code2 === "EAI_AGAIN") {
+    return new HttpTransportError(
+      "dns",
+      `could not resolve the judge hostname (${url}) \u2014 check the endpoint and DNS`,
+      { cause: err }
+    );
+  }
+  if (code2 === "ECONNREFUSED") {
+    return new HttpTransportError(
+      "connect_refused",
+      `judge refused the connection (${url}) \u2014 the service may be down or restarting`,
+      { cause: err }
+    );
+  }
+  if (code2 === "ECONNRESET" || code2 === "EPIPE") {
+    return new HttpTransportError(
+      "connection_reset",
+      `judge dropped the connection mid-request (${url}) \u2014 retry once`,
+      { cause: err }
+    );
+  }
+  return new HttpTransportError(
+    "unknown",
+    `${method} ${url} failed: ${err instanceof Error ? err.message : String(err)}`,
+    { cause: err }
+  );
+}
 
 // src-ts/browser/keyLoader.ts
 init_define_ATBASH_CHROMIA_NODE_URLS();
@@ -44573,6 +44633,7 @@ var Atbash = class _Atbash {
   failClosed;
   /** Org key learned from the last agent-exists check, for this agent only. */
   _orgKeyFromChain = null;
+  debug;
   logger;
   http;
   /**
@@ -44586,6 +44647,8 @@ var Atbash = class _Atbash {
    * server-side replay protection windows never expire it mid-session.
    */
   _authBearer = null;
+  /** Guards `logEnvironmentOnce` — hosts construct several clients. */
+  static environmentLogged = false;
   constructor(privkey, options = {}) {
     this.auth = native.loadAgent(privkey);
     this.endpoint = (options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "") || DEFAULT_ENDPOINT;
@@ -44595,8 +44658,10 @@ var Atbash = class _Atbash {
     this.verifyPubKey = options.verifyPubKey;
     this.orgEncryptionPubKey = options.orgEncryptionPubKey;
     this.failClosed = options.failClosed !== false;
+    this.debug = options.debug === true;
     this.logger = options.logger ?? {};
-    this.http = new HttpClient(this.endpoint, options.timeoutMs ?? 3e4);
+    this.http = new HttpClient(this.endpoint, options.timeoutMs ?? 6e4);
+    this.logEnvironmentOnce();
     if (this.endpoint !== DEFAULT_ENDPOINT) {
       this.logger.warn?.("[atbash] running on non-default judge endpoint", {
         endpoint: this.endpoint,
@@ -44604,6 +44669,31 @@ var Atbash = class _Atbash {
       });
     }
   }
+  /**
+   * Say which environment this build talks to, once per process.
+   *
+   * The endpoint and both chain RIDs are compiled in, chosen by the npm tag,
+   * and no configuration repoints a released build. So installing the build
+   * for the wrong environment is invisible: the plugin loads, the hook fires,
+   * and every judge call fails because the agent does not exist on the chain
+   * this build targets. Organisation names are not unique across environments
+   * either, so an org resolving is not evidence the build is right.
+   */
+  logEnvironmentOnce() {
+    if (_Atbash.environmentLogged) return;
+    _Atbash.environmentLogged = true;
+    const brief = (rid) => rid ? `${rid.slice(0, 8)}\u2026` : "(unset)";
+    this.logger.info?.(
+      `[atbash] environment \u2014 judge=${this.endpoint} publicChain=${brief(native.DEFAULT_BLOCKCHAIN_RID)} privateChain=${brief(native.DEFAULT_PRIVATE_BLOCKCHAIN_RID)} activeChain=${brief(this.blockchainRid)} responseSignatureCheck=${this.verifyPubKey ? "on" : "off"}`,
+      {
+        judgeEndpoint: this.endpoint,
+        publicBlockchainRid: native.DEFAULT_BLOCKCHAIN_RID,
+        privateBlockchainRid: native.DEFAULT_PRIVATE_BLOCKCHAIN_RID,
+        activeBlockchainRid: this.blockchainRid,
+        responseSignatureCheck: Boolean(this.verifyPubKey)
+      }
+    );
+  }
   /**
    * Construct from resolved config: explicit overrides → env vars → the
    * `~/.config/atbash/config.json` file (see userConfig.resolve). The private
@@ -44627,6 +44717,9 @@ var Atbash = class _Atbash {
       orgName: options.orgName,
       verifyPubKey: validated.verifyPubKey ?? void 0,
       failClosed: options.failClosed,
+      // ATBASH_DEBUG lets an operator turn diagnostics on without editing a
+      // host's plugin config, which is usually the harder half.
+      debug: options.debug ?? /^(1|true|yes)$/i.test(resolve("debug")),
       logger: options.logger
     });
   }
@@ -44872,8 +44965,9 @@ var Atbash = class _Atbash {
       });
       if (result.verdict === "No verdict") {
         if (result.status !== "logged") {
-          return this.fail(
+          return this.failJudge(
             `judge returned no verdict without an audit-tier marker (status: ${result.status || "absent"})`,
+            void 0,
             result.toolCallId
           );
         }
@@ -44925,16 +45019,38 @@ var Atbash = class _Atbash {
           toolCallId: result.toolCallId
         };
       }
-      return this.fail(
+      return this.failJudge(
         "unrecognized action_type from judge",
+        void 0,
         result.toolCallId
       );
     } catch (err) {
-      const message = errorMessage(err);
-      this.logger.warn?.("[atbash] judge API failed", { reason: message });
-      return this.fail(message);
+      return this.failJudge(errorMessage(err), err);
     }
   }
+  /**
+   * One exit for every judge failure.
+   *
+   * Status and reason go in the *message*, not only in the meta object: hosts
+   * print the message and drop the meta, which is why this read as a bare
+   * "judge API failed" while the judge was answering with a precise reason.
+   * The response body follows only under `debug`, since it can echo the action.
+   */
+  failJudge(reason, cause, toolCallId) {
+    const api2 = cause instanceof AtbashAPIError ? cause : null;
+    const status = api2 ? ` status=${api2.status || "no-response"}` : "";
+    const body = this.debug && api2?.body ? ` body=${truncate(api2.body, 500)}` : "";
+    this.logger.warn?.(
+      `[atbash] judge API failed \u2014${status} reason=${truncate(reason, 300)}${body}`,
+      {
+        reason,
+        ...api2 ? { status: api2.status, body: api2.body } : {},
+        endpoint: this.endpoint,
+        ...toolCallId ? { toolCallId } : {}
+      }
+    );
+    return this.fail(reason, toolCallId);
+  }
   fail(reason, toolCallId) {
     return { allow: !this.failClosed, verdict: "ERROR", reason, toolCallId };
   }
@@ -45275,8 +45391,27 @@ var Atbash = class _Atbash {
       this.endpoint
     );
   }
-  /** Wrap a *transport* failure (fetch threw, no response) as an AtbashAPIError. */
+  /**
+   * Wrap a transport failure (fetch threw, no response) as an AtbashAPIError.
+   *
+   * `HttpTransportError.kind` names the cause; the message is already
+   * human-readable. `debug` echoes the original exception so operators can
+   * cross-reference with node / undici logs when a class doesn't match.
+   */
   transportError(err) {
+    if (err instanceof HttpTransportError) {
+      if (this.debug) {
+        this.logger.warn?.(
+          `[atbash] transport failed \u2014 kind=${err.kind}`,
+          {
+            kind: err.kind,
+            cause: err.cause instanceof Error ? err.cause.message : String(err.cause ?? ""),
+            endpoint: this.endpoint
+          }
+        );
+      }
+      return new AtbashAPIError(0, err.message, "", this.endpoint);
+    }
     return new AtbashAPIError(0, errorMessage(err), "", this.endpoint);
   }
   async json(resp) {
@@ -45422,9 +45557,32 @@ function stringifyArgs(args) {
   }
 }
 var MAX_ACTION_LEN = 4e3;
-function truncate(text) {
-  if (text.length <= MAX_ACTION_LEN) return text;
-  return text.slice(0, MAX_ACTION_LEN) + "\u2026";
+function truncate(text, limit = MAX_ACTION_LEN) {
+  if (text.length <= limit) return text;
+  return text.slice(0, limit) + "\u2026";
+}
+
+// src-ts/key-path.ts
+init_define_ATBASH_CHROMIA_NODE_URLS();
+init_define_ATBASH_PRIVATE_NODE_URLS();
+import { homedir } from "os";
+import { join as join2 } from "path";
+var KEY_DIR_REL = ".config/atbash";
+var KEY_FILENAMES = ["guard-client-key", "atbash-client-key"];
+function home() {
+  return process.env.HOME || homedir() || "";
+}
+function expandHome(p) {
+  if (!p.startsWith("~/")) return p;
+  return join2(home(), p.slice(2));
+}
+function keyPathCandidates() {
+  return KEY_FILENAMES.map((name2) => join2(home(), KEY_DIR_REL, name2));
+}
+function chooseKeyPath(input, exists) {
+  if (input) return expandHome(input);
+  const candidates = keyPathCandidates();
+  return candidates.find(exists) ?? candidates[0];
 }
 
 // src-ts/redact.ts
@@ -45471,6 +45629,19 @@ function verifyJudgeResponseSignature(bodyBytes, signatureHex, pubKeyHex) {
   };
 }
 
+// src-ts/memory/boot-sync-message.ts
+init_define_ATBASH_CHROMIA_NODE_URLS();
+init_define_ATBASH_PRIVATE_NODE_URLS();
+var BOOT_SYNC_HINT = "check the chain endpoint and orgName if the cause above does not explain it";
+function bootSyncFailureLine(cause) {
+  const reason = cause instanceof Error ? cause.message : String(cause);
+  const trimmed = reason.trim();
+  return trimmed ? `[atbash] boot memory sync failed: ${trimmed}` : (
+    // No cause to show: fall back to the advice rather than a bare colon.
+    `[atbash] boot memory sync failed \u2014 ${BOOT_SYNC_HINT}`
+  );
+}
+
 // src-ts/memory/index.ts
 init_define_ATBASH_CHROMIA_NODE_URLS();
 init_define_ATBASH_PRIVATE_NODE_URLS();
@@ -45876,6 +46047,7 @@ function diffMemorySnapshots2(before, after) {
 export {
   Atbash,
   AtbashAPIError,
+  BOOT_SYNC_HINT,
   DEFAULT_BLOCKCHAIN_RID,
   DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT,
@@ -45883,11 +46055,16 @@ export {
   DEFAULT_MEMORY_READ_TOOL_NAMES,
   DEFAULT_MEMORY_WRITE_TOOL_NAMES,
   EciesDomain,
+  HttpClient,
+  HttpTransportError,
+  KEY_FILENAMES,
   MemoryGuardManager,
   MemoryIntegrityError,
   PointerStore,
   SignatureVerificationError,
+  bootSyncFailureLine,
   buildAllowedJudgeHosts,
+  chooseKeyPath,
   claimHashHex,
   classifyMemoryRead,
   classifyMemoryWrite,
@@ -45922,6 +46099,7 @@ export {
   isEnvelope,
   isValidPrivateKey2 as isValidPrivateKey,
   keyFingerprintOf,
+  keyPathCandidates,
   loadAgent2 as loadAgent,
   loadAgentFromFile,
   loadUserConfig,