fix(wallet): type key-resolution failures, and validate refs at init

Finding 6 and the validation trio.

**Key resolution failures are typed at the throw.**

`resolveKeyRef` and the keystore decrypt run at *use* time, from inside
the client construction every signing command performs before its try
block — so a plain Error reached incur's top-level handler and rendered
as `{ code: 'UNKNOWN' }`, no code and no `retryable`. That is what an
agent saw for the most common failure a vault-backed wallet has:
installed, but not logged in.

The obvious fix — move construction inside each command's try — would
have made it worse. Those catches end in `out.fail('UPLOAD_FAILED', …)`,
`'COSTS_FAILED'`, `'DATASET_LIST_FAILED'`, so a key that could not be
fetched would be reported as an upload that failed: typed, and wrong.
Throwing `Errors.IncurError` instead fixes all 15 commands at once,
plus any command that does not exist yet, and needs no command edits.

Codes are shared with the ones `walletPreflight` already emits for the
same conditions — whether the guard caught it or the resolver did is an
implementation detail, and the fix is identical either way. New at use
time: `KEY_REF_RESOLUTION_FAILED` (provider ran and refused — explicitly
not retryable, since every cause needs a deliberate act),
`KEY_REF_NOT_A_KEY`, `KEY_REF_AMBIGUOUS`, `KEYSTORE_DECRYPT_FAILED`,
`KEYSTORE_NOT_A_KEY`, `KEYSTORE_AMBIGUOUS`.

**A leading `-` is no longer a legal reference.**

`clawdi:--project` passed SAFE_REF and reached argv as `clawdi vault
resolve --project`, so config steered the helper's own option parsing
rather than naming a secret. Not arbitrary execution, but more than
"only the reference comes from config" allows. A dash anywhere else
stays legal — `FILECOIN-PRIVATE-KEY` still resolves.

**`wallet init` refuses what no command could resolve.**

It validated the `<provider>:<ref>` shape and nothing else, so
`clawdi:MY KEY&touch x` returned `configured`, cleared the previous
wallet, and left every later command failing with "re-run `foc-cli
wallet init`" — pointing back at the command that had just accepted it.
The check is shared with the resolver via `unsafeRefReason`, and the
preflight applies it too so a config already holding one gets a CTA
instead of a bare throw mid-command.

**`--keyProject` on its own now does what both docs promise.**

No branch consumed it: the command fell through to `already_configured`,
wrote nothing, and reported success, so the caller believed a scope was
pinned that never was and every command kept resolving against the
provider's default project. It now re-scopes the configured reference.
Without one it fails `KEY_PROJECT_WITHOUT_KEY_REF`, and combined with
`--auto`/`--privateKey`/`--keystore` it is refused rather than shadowing
them — answering a contradiction by quietly picking one is the same
silent-ignore this removes.

Author: nijoe1

cli/src/client.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from 'node:child_process'
 import { basename, dirname } from 'node:path'
 import { getChain } from '@filoz/synapse-core/chains'
+import { Errors } from 'incur'
 import { createPublicClient, createWalletClient, type Hex, http } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
 import config from './config.ts'
@@ -15,6 +16,7 @@ import {
   providerNames,
   redactKeyLike,
   resolveKeyRef,
+  unsafeRefReason,
 } from './key-ref.ts'
 import type { OutputContext } from './output.ts'
 import { canPrompt, expandHome } from './utils.ts'
@@ -26,6 +28,21 @@ type Problem = {
   retryable?: boolean
 }
 
+/**
+ * "Reconfigure the reference", for the several ways a stored one can be broken.
+ * A wallet is configured (badly), so every suggestion carries --force or it
+ * would bounce off WALLET_ALREADY_CONFIGURED.
+ */
+function reconfigureRefCta() {
+  return {
+    description: 'Reconfigure the reference:',
+    commands: keyRefCtaCommands().map((cmd) => ({
+      ...cmd,
+      options: { ...cmd.options, force: true },
+    })),
+  }
+}
+
 /**
  * Cheap checks that must pass before a command can sign anything.
  *
@@ -76,14 +93,7 @@ export function walletPreflight(c: { agent?: boolean }): Problem | null {
         // passed to --key-ref, and this message is the one place that mistake
         // would be echoed into a log. The command to fix it says the shape.
         message: `The configured key reference (${redactKeyLike(raw)}) is not of the form <provider>:<reference> — e.g. clawdi:FILECOIN_PRIVATE_KEY. Reconfigure it with \`foc-cli wallet init --key-ref <provider>:<reference> --force\`.`,
-        cta: {
-          description: 'Reconfigure the reference:',
-          commands: keyRefCtaCommands().map((cmd) => ({
-            ...cmd,
-            // A wallet is configured (badly), so replacing it needs --force.
-            options: { ...cmd.options, force: true },
-          })),
-        },
+        cta: reconfigureRefCta(),
       }
     }
     // Before the PATH probe, which cannot tell "this provider does not exist"
@@ -95,13 +105,24 @@ export function walletPreflight(c: { agent?: boolean }): Problem | null {
       return {
         code: 'UNKNOWN_KEY_REF_PROVIDER',
         message: `The configured key reference names an unknown provider "${parsed.provider}". Supported: ${providerNames().join(', ')}. Reconfigure it with \`foc-cli wallet init --key-ref <provider>:<reference> --force\`.`,
-        cta: {
-          description: 'Reconfigure the reference:',
-          commands: keyRefCtaCommands().map((cmd) => ({
-            ...cmd,
-            options: { ...cmd.options, force: true },
-          })),
-        },
+        cta: reconfigureRefCta(),
+      }
+    }
+    // Cheap and config-only, so it belongs with the other guard checks rather
+    // than at use time: a reference or scope holding characters the resolver
+    // refuses is a permanent misconfiguration, and catching it here is what
+    // gives it a call to action instead of a bare throw mid-command.
+    for (const [what, value] of [
+      ['reference', parsed.ref],
+      ['project', config.get('keyRefProject')],
+    ] as const) {
+      const reason = value === undefined ? null : unsafeRefReason(value)
+      if (reason) {
+        return {
+          code: 'MALFORMED_KEY_REF',
+          message: `Malformed key ${what} in config: it ${reason}. Reconfigure the wallet with \`foc-cli wallet init --key-ref <provider>:<reference> --force\`.`,
+          cta: reconfigureRefCta(),
+        }
       }
     }
     if (!isProviderAvailable(parsed.provider)) {
@@ -220,9 +241,11 @@ function privateKeyFromConfig() {
   if (!keystore) {
     const privateKey = config.get('privateKey')
     if (!privateKey) {
-      throw new Error(
-        'Private key not found. Please run `foc-cli wallet init` to initialize the CLI'
-      )
+      throw new Errors.IncurError({
+        code: 'WALLET_NOT_CONFIGURED',
+        message:
+          'Private key not found. Please run `foc-cli wallet init` to initialize the CLI',
+      })
     }
     return privateKey
   }
@@ -249,13 +272,18 @@ function privateKeyFromConfig() {
     // through to the terminal; this message decodes what that output means
     // rather than re-reading it.
     if ((error as { code?: string }).code === 'ENOENT') {
-      throw new Error(
-        'Failed to access keystore: Foundry `cast` is not on PATH. Install Foundry (https://getfoundry.sh), or switch to a private-key wallet with `foc-cli wallet init`.'
-      )
+      throw new Errors.IncurError({
+        code: 'KEYSTORE_TOOL_MISSING',
+        retryable: true,
+        message:
+          'Failed to access keystore: Foundry `cast` is not on PATH. Install Foundry (https://getfoundry.sh), or switch to a private-key wallet with `foc-cli wallet init`.',
+      })
     }
-    throw new Error(
-      'Failed to access keystore. "Mac Mismatch" above means the password was wrong. Other causes: an invalid keystore file, or a session with no terminal for the password prompt — keystore mode is interactive-only, so MCP/CI must use a private-key wallet.'
-    )
+    throw new Errors.IncurError({
+      code: 'KEYSTORE_DECRYPT_FAILED',
+      message:
+        'Failed to access keystore. "Mac Mismatch" above means the password was wrong. Other causes: an invalid keystore file, or a session with no terminal for the password prompt — keystore mode is interactive-only, so MCP/CI must use a private-key wallet.',
+    })
   }
 
   // The same bounded matcher the key-reference path uses, for the same reason:
@@ -265,14 +293,17 @@ function privateKeyFromConfig() {
   // same shape, one matcher.
   const found = findPrivateKeys(extraction)
   if (found.length === 0) {
-    throw new Error(
-      "Keystore decrypted, but no private key (0x + 64 hex, on its own rather than inside a longer value) was found in cast's output. Check `cast wallet decrypt-keystore` works on this file directly — the output is not shown here on purpose."
-    )
+    throw new Errors.IncurError({
+      code: 'KEYSTORE_NOT_A_KEY',
+      message:
+        "Keystore decrypted, but no private key (0x + 64 hex, on its own rather than inside a longer value) was found in cast's output. Check `cast wallet decrypt-keystore` works on this file directly — the output is not shown here on purpose.",
+    })
   }
   if (found.length > 1) {
-    throw new Error(
-      `Keystore decrypted to output containing ${found.length} different 0x + 64 hex values, so which one is the key is ambiguous. Use a keystore that holds a single key — the values are not shown here on purpose.`
-    )
+    throw new Errors.IncurError({
+      code: 'KEYSTORE_AMBIGUOUS',
+      message: `Keystore decrypted to output containing ${found.length} different 0x + 64 hex values, so which one is the key is ambiguous. Use a keystore that holds a single key — the values are not shown here on purpose.`,
+    })
   }
   return found[0]
 }

cli/src/commands/wallet/init.ts

@@ -11,6 +11,7 @@ import {
   parseKeyRef,
   providerNames,
   redactKeyLike,
+  unsafeRefReason,
 } from '../../key-ref.ts'
 import { commandOutput, OutputContext } from '../../output.ts'
 import { canPrompt, expandHome, isAgent } from '../../utils.ts'
@@ -326,6 +327,79 @@ export const initCommand = {
       config.set('source', c.options.source)
     }
 
+    // --keyProject on its own re-scopes the reference already configured. Both
+    // reference docs tell the reader to do exactly this, and describe it as
+    // never blocked — which was true, but only because nothing consumed it:
+    // no branch matched, so the command fell through to `already_configured`,
+    // wrote nothing, and reported success. The caller then believed a scope was
+    // pinned that never was, and every command kept resolving against the
+    // provider's default project.
+    if (c.options.keyProject !== undefined && !c.options.keyRef) {
+      // Paired with a method that configures a different custody mode there is
+      // nothing for a scope to apply to, and this branch runs before those
+      // methods — so say so rather than either shadowing them or repeating the
+      // silent-ignore this whole branch exists to remove.
+      if (c.options.auto || c.options.privateKey || c.options.keystore) {
+        return out.fail(
+          'KEY_PROJECT_WITHOUT_KEY_REF',
+          '--key-project scopes a key reference, and --auto, --private-key and --keystore all configure a wallet that uses none. Drop --key-project, or configure a reference with --key-ref instead.'
+        )
+      }
+      const currentRef = config.get('keyRef')
+      if (!currentRef) {
+        return out.fail(
+          'KEY_PROJECT_WITHOUT_KEY_REF',
+          '--key-project scopes a key reference, and this wallet does not use one. Pass --key-ref <provider>:<reference> alongside it, or drop --key-project.',
+          {
+            cta: {
+              description: 'Configure a reference and its scope together:',
+              commands: keyRefCtaCommands().map((cmd) => ({
+                ...cmd,
+                options: { ...cmd.options, keyProject: c.options.keyProject },
+              })),
+            },
+          }
+        )
+      }
+      const badProject = c.options.keyProject
+        ? unsafeRefReason(c.options.keyProject)
+        : null
+      if (badProject) {
+        return out.fail(
+          'INVALID_KEY_PROJECT',
+          `Invalid key project: it ${badProject}.`
+        )
+      }
+
+      out.step('Scoping key reference')
+      // An empty value is how a scope is dropped deliberately — the same
+      // convention the --keyRef branch below uses.
+      if (c.options.keyProject) {
+        config.set('keyRefProject', c.options.keyProject)
+      } else {
+        config.delete('keyRefProject')
+      }
+      const parsed = parseKeyRef(currentRef)
+      const providerAvailable = parsed
+        ? isProviderAvailable(parsed.provider)
+        : false
+      if (!agent) {
+        out.success(
+          c.options.keyProject
+            ? `Key reference ${currentRef} is now scoped to project ${c.options.keyProject}.`
+            : `Key reference ${currentRef} is no longer scoped to a project.`
+        )
+        p.outro("You're all set!")
+      }
+      return out.done({
+        status: 'configured',
+        method: 'keyRef',
+        keyRef: currentRef,
+        keyProject: config.get('keyRefProject'),
+        providerAvailable,
+      })
+    }
+
     // Before --keystore and --privateKey so an explicit method always wins, and
     // deliberately allowed in agent mode: unlike a keystore there is no prompt,
     // so this is the one custody mode that works from MCP with no key at rest.
@@ -349,6 +423,28 @@ export const initCommand = {
           `Unknown key-reference provider "${parsed.provider}". Supported: ${providerNames().join(', ')}.`
         )
       }
+      // Init is the only moment this is cheap to catch, and the file says so
+      // about keystore paths a few lines up. Without it, a reference the
+      // resolver will always refuse was stored anyway — `wallet init` reported
+      // `configured` and cleared the previous wallet, and every command after
+      // it failed with "re-run `foc-cli wallet init`", pointing back at the
+      // command that had just accepted the value.
+      const badRef = unsafeRefReason(parsed.ref)
+      if (badRef) {
+        return out.fail(
+          'INVALID_KEY_REF',
+          `Invalid key reference: it ${badRef}.`
+        )
+      }
+      const badProject = c.options.keyProject
+        ? unsafeRefReason(c.options.keyProject)
+        : null
+      if (badProject) {
+        return out.fail(
+          'INVALID_KEY_PROJECT',
+          `Invalid key project: it ${badProject}.`
+        )
+      }
       // Validate the shape only, not that it resolves. Resolution needs the
       // provider to be installed and authenticated, which is a different
       // failure with a different fix — and init must stay usable while setting