fix(cts): act on the review of the 0.42.3 reconciliation (CIP-3727)

Four of the five findings. The fifth is declined, with a reason.

Two are staleness the precedence flip left behind — it made upstream's `help`
win, which moved the dashboard link out of `message` and onto `url`, and two
shipped documents still told a reader to look in the message:

- `skills/stash-auth/SKILL.md` claimed "nothing upstream attaches a URL to
  them, which is why the dashboard link is written into `message`". That is
  false as of 0.42.3, contradicted this PR's own changeset, and contradicted
  the paragraph twenty lines above it that points at `failure.url`. Skills ship
  in the `stash` tarball, so the wrong sentence lands in a customer's repo.
- `EncryptionError.authCode`'s JSDoc said the same thing in a published `.d.ts`.

One is a real asymmetry, and it falsified a claim in the changeset. `code` is
the one carried key with a CLOSED type, and the wasm entry screened it in
`toFailure` but not on the thrown-init path, which reached the caller through
`carryDiagnostics` alone — a deliberately structural copy, so that it cannot
drop a field protect-ffi adds next. The two seams of the same entry therefore
disagreed about a check the native entry applies to both, and a fetch failing
inside a JS auth strategy could hand back `code: 'ECONNRESET'` wearing
`ProtectErrorCode`. The screen now runs once, inside `carryDiagnostics`, so it
cannot be forgotten at a third call site. `authCode` is deliberately untouched:
that set is open and a newer code must still arrive.

One is a code/prose disagreement of exactly the kind the CLI's two tables exist
to prevent. `stash env`'s profile-load arm already rendered a terminal hint —
"logging in again will not clear this" — while hardcoding `not_logged_in`, so
an agent read the code, ran `stash auth login`, and arrived back. It now routes
through `authFailureCliCode` like the renewal arm.

DECLINED: `stash auth login` reports `USAGE_LIMIT_EXCEEDED` on `--json` while
`stash env` reports `usage_limit_exceeded`. Real, but `login`'s code for an auth
failure has always been `failure.type` verbatim (`EXPIRED_TOKEN` and the rest),
which predates this work and is documented in `skills/stash-cli`. Collapsing the
two spellings changes an existing machine-readable contract for every code, not
just these, and belongs in its own change rather than riding along here.

Claude-Session: https://claude.ai/code/session_01PS9J6pu3FmmQvJHxwTVJUc

Author: tobyhede

.changeset/usage-limit-refusal-guidance.md

@@ -26,7 +26,8 @@ supplies one naming the same destinations.
 ```typescript
 const result = await client.encrypt(value, { column, table })
 if (result.failure?.authCode === 'USAGE_LIMIT_EXCEEDED') {
-  // Stop retrying. `result.failure.message` names dashboard.cipherstash.com.
+  // Stop retrying. `result.failure.message` says what to do about it,
+  // `result.failure.url` is where — the link is never folded into the message.
 }
 ```
 
@@ -66,8 +67,10 @@ diagnosis, and no longer answer a billing refusal with "run `stash auth login`
 and try again" — a fresh login cannot mint a credential that is being withheld
 on billing grounds. `stash env` reports the two terminal refusals under their
 own codes, `usage_limit_exceeded` and `org_not_provisioned`, rather than
-`session_invalid`: `code` is the only machine-readable field on the stream, so
-reporting a stale session sends an agent round a re-login loop it cannot win.
+`session_invalid` or `not_logged_in`: `code` is the only machine-readable field
+on the stream, so reporting a stale session sends an agent round a re-login loop
+it cannot win. Both of its failure arms do this — the one that loads the device
+session as well as the one that renews it.
 
 The `--json` error envelope gains an optional `hint`, carrying that remedy. It
 was previously printed only on the interactive path, which left the dashboard

packages/cli/src/commands/env/__tests__/env.test.ts

@@ -178,6 +178,40 @@ function lastJson(): Record<string, unknown> {
   return JSON.parse(logSpy.mock.calls.at(-1)?.[0] as string)
 }
 
+describe('envCommand — a terminal refusal at profile load', () => {
+  /**
+   * `fromProfile()` itself fails — no session on disk, or one CTS will not
+   * honour.
+   */
+  function stubStrategyFailure(type: string, message: string) {
+    authMock.DeviceSessionStrategy.fromProfile.mockReturnValue({
+      failure: { type, error: new Error(message) },
+    })
+  }
+
+  // The profile-load arm renders a terminal hint too, so its `code` has to
+  // agree with it. It used to report `not_logged_in` while the hint said
+  // logging in again would not help.
+  it('reports the refusal code rather than not_logged_in', async () => {
+    stubStrategyFailure('USAGE_LIMIT_EXCEEDED', 'Over the limit.')
+
+    await expectExit(envCommand({ name: 'x', json: true }), 1)
+
+    expect(lastJson()).toMatchObject({
+      status: 'error',
+      code: 'usage_limit_exceeded',
+    })
+  })
+
+  it('still reports not_logged_in for an ordinary profile failure', async () => {
+    stubStrategyFailure('NOT_AUTHENTICATED', 'No profile.')
+
+    await expectExit(envCommand({ name: 'x', json: true }), 1)
+
+    expect(lastJson()).toMatchObject({ status: 'error', code: 'not_logged_in' })
+  })
+})
+
 describe('envCommand — a CTS refusal at session renewal', () => {
   /**
    * `fromProfile()` succeeds (there IS a session on disk) and the renewal is

packages/cli/src/commands/env/index.ts

@@ -342,8 +342,14 @@ async function mintCredentials(keyName: string): Promise<MintedCredentials> {
   // 1. Device session from ~/.cipherstash (written by `stash auth login`).
   const strategyResult = DeviceSessionStrategy.fromProfile()
   if (strategyResult.failure) {
+    // `authFailureCliCode` for the same reason as the renewal arm below: this
+    // arm already calls `authFailureHint`, so it can print "logging in again
+    // will not clear this" — and pairing that with a hardcoded
+    // `not_logged_in` is the exact code/prose disagreement the two tables
+    // exist to prevent. An agent reads `code`, runs `stash auth login`, and
+    // arrives back here.
     throw new MintError(
-      'not_logged_in',
+      authFailureCliCode(strategyResult.failure, 'not_logged_in'),
       `Not logged in: ${authFailureMessage(strategyResult.failure)}`,
       authFailureHint(strategyResult.failure, LOGIN_HINT),
     )

packages/stack/__tests__/wasm-inline-auth-failure.test.ts

@@ -234,6 +234,36 @@ describe('a usage-limit refusal at wasm-inline client init', () => {
     expect(error.message).toContain('[encryption]:')
   })
 
+  it('does not let a foreign `code` reach the thrown init error', async () => {
+    // `code` is the one carried key with a CLOSED type, and the init path
+    // reached the caller through `carryDiagnostics` alone — which copies keys
+    // structurally, on purpose, so it cannot drop a field protect-ffi adds
+    // next. That left this seam accepting anything: a fetch failing inside a
+    // JS auth strategy rejects with `ECONNRESET`, and the caller got it
+    // wearing `ProtectErrorCode`. `toFailure` had always screened it, so the
+    // two seams of this entry disagreed about the same check.
+    const error = await initFailure(
+      Object.assign(new Error('socket hang up'), {
+        code: 'ECONNRESET',
+        authCode: 'SOME_FUTURE_REFUSAL',
+      }),
+    )
+
+    expect(error).not.toHaveProperty('code')
+    // The open set is untouched: a code newer than this build still arrives.
+    expect(error.authCode).toBe('SOME_FUTURE_REFUSAL')
+  })
+
+  it('keeps a real protect-ffi code on the thrown init error', async () => {
+    const error = await initFailure(
+      Object.assign(new Error('bad config'), {
+        code: 'UNSUPPORTED_CONFIG_VERSION',
+      }),
+    )
+
+    expect(error.code).toBe('UNSUPPORTED_CONFIG_VERSION')
+  })
+
   it('rescues a bare-object refusal at init too', async () => {
     const error = await initFailure(usageLimitObject())
 

packages/stack/src/errors/index.ts

@@ -49,7 +49,9 @@ export interface EncryptionError {
    * that `type` cannot express — `USAGE_LIMIT_EXCEEDED` above all, which means
    * the organisation is over its billing allowance and no amount of retrying
    * or key rotation will clear it. `message` already carries the remedy in
-   * prose (including the dashboard URL); this field is for branching on it.
+   * prose, and {@link EncryptionError.url} carries the link that goes with it —
+   * the two are halves of one remedy, and the link is never folded into the
+   * message. This field is for branching on the condition.
    *
    * ```typescript
    * if (result.failure?.authCode === 'USAGE_LIMIT_EXCEEDED') {

packages/stack/src/wasm-inline.ts

@@ -602,6 +602,24 @@ function carryDiagnostics<T extends object>(source: unknown, target: T): T {
       // it beats turning a failure into a rejection.
     }
   }
+
+  // `code` is the one copied key with a CLOSED type, so it is the one key the
+  // structural copy above cannot be trusted with. Everything else is either
+  // open (`authCode`) or untyped prose (`help`, `url`), but `code` is declared
+  // `ProtectErrorCode`, and Node stamps `ECONNRESET` / `MODULE_NOT_FOUND` onto
+  // its own errors — so a rejection from a fetch inside a JS auth strategy
+  // would otherwise republish a foreign string wearing that type.
+  //
+  // `toFailure` has always run `readErrorCode` for exactly this reason; the
+  // thrown-init path reached the caller through `carryDiagnostics` alone and
+  // did not, which left the two seams of this entry disagreeing about a check
+  // the native entry applies to both. Dropping an unrecognised code (rather
+  // than mapping it to `UNKNOWN`) matches `readErrorCode` — see its docblock
+  // for why those two are different statements.
+  if ('code' in target && readErrorCode(target) === undefined) {
+    delete (target as { code?: unknown }).code
+  }
+
   return target
 }
 

skills/stash-auth/SKILL.md

@@ -135,9 +135,12 @@ same code rides on the thrown error: `(err as { authCode?: string }).authCode`.
 Two of those fields are new alongside `authCode`. `help` is the remedy text the
 failure arrived with — already folded into `message`, so you rarely need to read
 it separately — and `url` is a link the diagnostic carried, which is *not* folded
-in and reaches you only as `failure.url`. Neither is populated for the two codes
-above today: nothing upstream attaches a URL to them, which is why the dashboard
-link is written into `message` rather than left to `url`.
+in and reaches you only as `failure.url`.
+
+**For the two terminal codes, read both.** As of `stack-auth` 0.42.3 CipherStash
+attaches a `help` *and* a `url` to each, so `message` carries the prose and the
+link is on `failure.url` and nowhere else. Rendering `message` alone tells a
+user to upgrade their plan without telling them where.
 
 One shape to know: a refusal met by `LockContext.identify()` is an HTTP response
 rather than a thrown error, so its failure carries `type` and `authCode` but no