fix: quota denial message no longer tells the agent to retry (#144)

## Summary

When `/v1/assess` returns 429 `quota_exceeded` and `failOpen` /
`fail_open` is off, the gate denies with `api_error` and the
quota-specific `contact_merchant` instructions ("Do not retry: the same
503 will be returned until the merchant resolves the issue"). The reason
carried no message, so the body fell back to the `api_error` default,
"AgentScore is unreachable. This is transient: retry in a few seconds."
An agent reading both got two opposite instructions in one response.

The quota denial now carries its own message, `QUOTA_EXCEEDED_MESSAGE`:
"AgentScore identity verification is unavailable for this merchant.
Retrying will not help." Every place that builds the quota denial sets
it (the typed and the untyped 429 paths). Found in a docs audit while
checking the errors reference against the SDK's emitted bodies.

## Type of change

- [x] Bug fix (no breaking change)
- [ ] New feature (no breaking change)
- [ ] Breaking change (existing callers must update)
- [ ] Docs, tests, or internal maintenance only

## Public API

Adds the exported constant `QUOTA_EXCEEDED_MESSAGE` beside
`QUOTA_EXCEEDED_INSTRUCTIONS`. The 503 body's `error.message` on the
quota path changes text; its shape and status do not. No release is cut
for this alone; the next release carries it.

## Test plan

The quota tests now assert the message. Positive control: with the
message removed from the deny sites, those tests fail; restored, they
pass. Full lint, type check and test suite pass locally.

## Checklist

- [x] Tests cover the new behavior, and the suite passes locally
- [x] Lint, format, and type checks pass
- [x] Docs and README examples updated if the public surface changed (no
README text covers this message)
- [x] No secrets, credentials, or personal data in the diff or the tests

Author: vvillait88

src/_response.ts

@@ -73,6 +73,10 @@ const API_ERROR_INSTRUCTIONS = JSON.stringify({
     'Verification is temporarily unavailable. Please try again in a moment: this is a transient issue, not a problem with your account.',
 });
 
+// The message paired with QUOTA_EXCEEDED_INSTRUCTIONS. The api_error default says the failure is
+// transient and worth retrying, which contradicts the contact_merchant instructions on this path.
+export const QUOTA_EXCEEDED_MESSAGE = 'AgentScore identity verification is unavailable for this merchant. Retrying will not help.';
+
 export const QUOTA_EXCEEDED_INSTRUCTIONS = JSON.stringify({
   action: 'contact_merchant',
   steps: [

src/core.ts

@@ -9,7 +9,7 @@ import {
   TokenExpiredError,
 } from '@agent-score/sdk';
 import { isFixableDenial } from './_denial';
-import { QUOTA_EXCEEDED_INSTRUCTIONS } from './_response';
+import { QUOTA_EXCEEDED_INSTRUCTIONS, QUOTA_EXCEEDED_MESSAGE } from './_response';
 import { normalizeAddress } from './address';
 import { TTLCache } from './cache';
 import type { PaymentSigner } from './signer';
@@ -864,7 +864,7 @@ export function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScore
         if (failOpen) return { kind: 'allow', degraded: true, infraReason: 'quota_exceeded' };
         return {
           kind: 'deny',
-          reason: { code: 'api_error', agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS },
+          reason: { code: 'api_error', agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS, message: QUOTA_EXCEEDED_MESSAGE },
         };
       }
       if (err instanceof SdkTimeoutError) {
@@ -883,7 +883,7 @@ export function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScore
         if (failOpen) return { kind: 'allow', degraded: true, infraReason: 'quota_exceeded' };
         return {
           kind: 'deny',
-          reason: { code: 'api_error', agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS },
+          reason: { code: 'api_error', agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS, message: QUOTA_EXCEEDED_MESSAGE },
         };
       }
       if (errName === 'TimeoutError' || errName === 'AbortError') {

tests/edge-cases.test.ts

@@ -223,7 +223,9 @@ describe('error response edge cases', () => {
 
     expect(next).not.toHaveBeenCalled();
     expect(status).toHaveBeenCalledWith(503);
-    expect(json).toHaveBeenCalledWith(expect.objectContaining({ error: expect.objectContaining({ code: 'api_error' }) }));
+    expect(json).toHaveBeenCalledWith(expect.objectContaining({
+      error: expect.objectContaining({ code: 'api_error', message: expect.stringContaining('Retrying will not help') }),
+    }));
   });
 
   it('typed QuotaExceededError fails open (degraded allow) when failOpen is true', async () => {

tests/hono.test.ts

@@ -625,8 +625,9 @@ describe('Hono adapter: error paths', () => {
 
     const res = await app.request('/test', { headers: { 'x-wallet-address': WALLET } });
     expect(res.status).toBe(503);
-    const body = await res.json() as { error: { code: string }; agent_instructions: string };
+    const body = await res.json() as { error: { code: string; message: string }; agent_instructions: string };
     expect(body.error.code).toBe('api_error');
+    expect(body.error.message).toContain('Retrying will not help');
     const instructions = JSON.parse(body.agent_instructions);
     expect(instructions.action).toBe('contact_merchant');
     expect(instructions.steps[0]).toContain('merchant-side issue');