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

package/dist/index.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[]>;
@@ -585,6 +616,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 +628,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 +666,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 +1237,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, 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/index.d.ts

@@ -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[]>;
@@ -585,6 +616,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 +628,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 +666,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 +1237,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, 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/index.js

@@ -2856,6 +2856,7 @@ var src_ts_exports = {};
 __export(src_ts_exports, {
   Atbash: () => Atbash,
   AtbashAPIError: () => AtbashAPIError,
+  BOOT_SYNC_HINT: () => BOOT_SYNC_HINT,
   DEFAULT_BLOCKCHAIN_RID: () => DEFAULT_BLOCKCHAIN_RID,
   DEFAULT_CHROMIA_NODE_URLS: () => DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT: () => DEFAULT_ENDPOINT,
@@ -2863,11 +2864,14 @@ __export(src_ts_exports, {
   DEFAULT_MEMORY_READ_TOOL_NAMES: () => DEFAULT_MEMORY_READ_TOOL_NAMES,
   DEFAULT_MEMORY_WRITE_TOOL_NAMES: () => DEFAULT_MEMORY_WRITE_TOOL_NAMES,
   EciesDomain: () => EciesDomain,
+  KEY_FILENAMES: () => KEY_FILENAMES,
   MemoryGuardManager: () => MemoryGuardManager,
   MemoryIntegrityError: () => MemoryIntegrityError,
   PointerStore: () => PointerStore,
   SignatureVerificationError: () => SignatureVerificationError,
+  bootSyncFailureLine: () => bootSyncFailureLine,
   buildAllowedJudgeHosts: () => buildAllowedJudgeHosts,
+  chooseKeyPath: () => chooseKeyPath,
   claimHashHex: () => claimHashHex,
   classifyMemoryRead: () => classifyMemoryRead,
   classifyMemoryWrite: () => classifyMemoryWrite,
@@ -2902,6 +2906,7 @@ __export(src_ts_exports, {
   isEnvelope: () => isEnvelope,
   isValidPrivateKey: () => isValidPrivateKey,
   keyFingerprintOf: () => keyFingerprintOf,
+  keyPathCandidates: () => keyPathCandidates,
   loadAgent: () => loadAgent,
   loadAgentFromFile: () => loadAgentFromFile,
   loadUserConfig: () => loadUserConfig,
@@ -3135,18 +3140,31 @@ var HttpClient = class {
 
 // src-ts/keyLoader.ts
 var import_node_fs = require("fs");
+
+// src-ts/key-path.ts
 var import_node_os = require("os");
 var import_node_path = require("path");
-var DEFAULT_KEY_PATH_REL = ".config/atbash/guard-client-key";
-function resolveKeyPath(input) {
-  if (input) return expandHome(input);
-  const home = process.env.HOME || (0, import_node_os.homedir)() || "";
-  return (0, import_node_path.join)(home, DEFAULT_KEY_PATH_REL);
+var KEY_DIR_REL = ".config/atbash";
+var KEY_FILENAMES = ["guard-client-key", "atbash-client-key"];
+function home() {
+  return process.env.HOME || (0, import_node_os.homedir)() || "";
 }
 function expandHome(p) {
   if (!p.startsWith("~/")) return p;
-  const home = process.env.HOME || (0, import_node_os.homedir)() || "";
-  return (0, import_node_path.join)(home, p.slice(2));
+  return (0, import_node_path.join)(home(), p.slice(2));
+}
+function keyPathCandidates() {
+  return KEY_FILENAMES.map((name2) => (0, import_node_path.join)(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/keyLoader.ts
+function resolveKeyPath(input) {
+  return chooseKeyPath(input, import_node_fs.existsSync);
 }
 function readKeyFile(keyPath) {
   const content = String((0, import_node_fs.readFileSync)(keyPath, "utf8") || "").trim();
@@ -3176,6 +3194,12 @@ function readKeyFile(keyPath) {
 }
 function loadAgentFromFile(keyPath) {
   const resolved = resolveKeyPath(keyPath);
+  if (!(0, import_node_fs.existsSync)(resolved)) {
+    const looked = keyPath ? [resolved] : keyPathCandidates();
+    throw new Error(
+      `atbash key file not found. Looked for: ${looked.join(", ")}`
+    );
+  }
   const { privKey } = readKeyFile(resolved);
   return native.loadAgent(privKey);
 }
@@ -3218,8 +3242,8 @@ var durationHistogram = null;
 var defaultSource = "sdk";
 function isTelemetryOptedOut() {
   try {
-    const home = process.env.HOME || (0, import_node_os2.homedir)() || "";
-    const filePath = (0, import_node_path2.join)(home, ".config", "atbash", "telemetry.json");
+    const home2 = process.env.HOME || (0, import_node_os2.homedir)() || "";
+    const filePath = (0, import_node_path2.join)(home2, ".config", "atbash", "telemetry.json");
     const raw2 = (0, import_node_fs2.readFileSync)(filePath, "utf-8").trim();
     if (!raw2) return false;
     const config2 = JSON.parse(raw2);
@@ -3304,11 +3328,12 @@ var ENV_MAP = {
   judgeEndpoint: "ATBASH_ENDPOINT",
   blockchainRid: "ATBASH_BLOCKCHAIN_RID",
   provider: "ATBASH_PROVIDER",
-  providerModel: "ATBASH_PROVIDER_MODEL"
+  providerModel: "ATBASH_PROVIDER_MODEL",
+  debug: "ATBASH_DEBUG"
 };
 function getConfigDir() {
-  const home = process.env.HOME || (0, import_node_os3.homedir)() || "";
-  return (0, import_node_path3.join)(home, ".config", "atbash");
+  const home2 = process.env.HOME || (0, import_node_os3.homedir)() || "";
+  return (0, import_node_path3.join)(home2, ".config", "atbash");
 }
 function getConfigPath() {
   return (0, import_node_path3.join)(getConfigDir(), "config.json");
@@ -3367,6 +3392,7 @@ var Atbash = class _Atbash {
   failClosed;
   /** Org key learned from the last agent-exists check, for this agent only. */
   _orgKeyFromChain = null;
+  debug;
   logger;
   http;
   /**
@@ -3380,6 +3406,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;
@@ -3389,8 +3417,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.logEnvironmentOnce();
     if (this.endpoint !== DEFAULT_ENDPOINT) {
       this.logger.warn?.("[atbash] running on non-default judge endpoint", {
         endpoint: this.endpoint,
@@ -3398,6 +3428,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
@@ -3421,6 +3476,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
     });
   }
@@ -3666,8 +3724,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
           );
         }
@@ -3719,16 +3778,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 };
   }
@@ -4216,9 +4297,9 @@ 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/redact.ts
@@ -4261,6 +4342,17 @@ function verifyJudgeResponseSignature(bodyBytes, signatureHex, pubKeyHex) {
   };
 }
 
+// src-ts/memory/boot-sync-message.ts
+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/crypto.ts
 async function deriveMemoryKey(privkey) {
   return native.deriveMemoryKey(privkey);
@@ -4286,6 +4378,19 @@ async function scanMemory(entry, auth, opts) {
     toolArgsJson: opts?.toolArgsJson ?? JSON.stringify({ key: entry.key, source: entry.source }),
     mode: "memory-scan"
   });
+  const knownAction = result.actionType === "allow" || result.actionType === "block" || result.actionType === "hold_for_user_confirm";
+  const missingVerdict = result.verdict === "No verdict" && result.status !== "logged";
+  const unknownAction = result.actionType !== "" && !knownAction;
+  if (missingVerdict || unknownAction) {
+    return {
+      safe: false,
+      verdict: "red",
+      reason: unknownAction ? `judge returned unrecognised action_type "${result.actionType}"` : "judge returned no verdict",
+      confidence: result.confidence,
+      score: native.defaultScoreForVerdict("red"),
+      toolCallId: result.toolCallId
+    };
+  }
   const verdict = native.mapVerdict(
     result.actionType,
     result.confidence,
@@ -42436,6 +42541,10 @@ var index = /* @__PURE__ */ getDefaultExportFromCjs(builtExports);
 
 // src-ts/memory/chain.ts
 var { createClient, encryption: encryption2, newSignatureProvider: newSignatureProvider2, Buffer: PolyBuffer } = index;
+var FAILOVER_CONFIG = {
+  strategy: "tryNextOnError",
+  attemptsPerEndpoint: 1
+};
 function toGtxBytes(bytes) {
   return PolyBuffer.from(new Uint8Array(bytes));
 }
@@ -42465,7 +42574,11 @@ function materializeChain(chainOpts) {
 }
 async function buildChainClient(chainOpts) {
   const { nodeUrls, blockchainRid } = materializeChain(chainOpts);
-  return createClient({ nodeUrlPool: [...nodeUrls], blockchainRid });
+  return createClient({
+    nodeUrlPool: [...nodeUrls],
+    blockchainRid,
+    failOverConfig: FAILOVER_CONFIG
+  });
 }
 function buildSigner(auth) {
   const privKeyBuf = Buffer.from(auth.privkey, "hex");
@@ -42903,7 +43016,10 @@ var MemoryGuardManager = class {
       await this.pointerStore.set(this.agentPubkeyHex, result.pointer);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      this.logger.warn("[atbash] boot memory sync failed \u2014 check chain endpoint / orgName", { error: msg });
+      this.logger.warn(bootSyncFailureLine(err), {
+        error: msg,
+        hint: BOOT_SYNC_HINT
+      });
     }
   }
   /**
@@ -43132,6 +43248,7 @@ function diffMemorySnapshots(before, after) {
 0 && (module.exports = {
   Atbash,
   AtbashAPIError,
+  BOOT_SYNC_HINT,
   DEFAULT_BLOCKCHAIN_RID,
   DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT,
@@ -43139,11 +43256,14 @@ function diffMemorySnapshots(before, after) {
   DEFAULT_MEMORY_READ_TOOL_NAMES,
   DEFAULT_MEMORY_WRITE_TOOL_NAMES,
   EciesDomain,
+  KEY_FILENAMES,
   MemoryGuardManager,
   MemoryIntegrityError,
   PointerStore,
   SignatureVerificationError,
+  bootSyncFailureLine,
   buildAllowedJudgeHosts,
+  chooseKeyPath,
   claimHashHex,
   classifyMemoryRead,
   classifyMemoryWrite,
@@ -43178,6 +43298,7 @@ function diffMemorySnapshots(before, after) {
   isEnvelope,
   isValidPrivateKey,
   keyFingerprintOf,
+  keyPathCandidates,
   loadAgent,
   loadAgentFromFile,
   loadUserConfig,