CLI: arguments are tokenized twice (router → handler), silently corrupting structural payloads

[spouletmathis]

Summary

Command arguments are tokenized twice on their way to a handler: once by the router, once by the handler itself. Every structural payload (JSON objects, quoted values, comma-separated lists) therefore has to survive a second de-quoting pass it was never meant to go through.

This is not a hypothetical. It has produced at least two distinct user-visible bugs, and the current fixes patch the symptom rather than the shape:

• lending positions-batch --users a,b prepends a stray quote to the first address, always failing validation #57 — lending positions-batch --users a,b prepended a stray quote to the first address, failing validation every time.
• A recent --json regression — alter-cli mcp <tool> --json '{...}' rejected all payloads with Error: invalid --json: Unexpected character, taking down the entire script-facing entry point. Fixed on main, never shipped in a release.

Filing this so the class of bug is tracked, not just its instances.

The mechanism

argv  →  cli_execution.dart   re-quotes structural args  (quoteIfNeeded)
      →  command_router.dart  tokenizes, strips quotes, re-joins to a String
      →  handler              tokenizes AGAIN, strips quotes again
      →  jsonDecode / validation

Step 2 is the problem: the router flattens List<String> back into a String, so anything the shell already unquoted must be re-protected — by hand, correctly, at every hop. Miss it once and the payload is silently corrupted rather than rejected.

The --json regression is exactly that miss. On the real binary:

DBG input=mcp chain.add --json {"chain_id":100} --timeout 20
DBG tokens=[mcp, chain.add, --json, {chain_id:100}, --timeout, 20]
Error: invalid --json: Unexpected character

{"chain_id":100} reached jsonDecode as {chain_id:100}. Bisected to 16b841339, which rewrote GrammarParser.tokenize to handle quotes — a correct change in isolation that broke a caller relying on the old behaviour.

Both fixes so far (#57, bbdad4a5) add a compensating re-quote at the point where breakage was observed. That works, but the next flag carrying structural data starts from the same footing.

Why it matters beyond the two known cases

The failure mode is quiet. A corrupted payload does not look like a parsing bug at the call site — it surfaces as invalid --json, or as a validation error on an address that looks fine in the shell history. For a script-based caller there is no way to tell "you passed bad JSON" from "the CLI mangled your JSON".

Suggested direction

Not prescriptive, but the options seem to be:

1. Keep tokens as List<String> end to end — pass the parsed argv to handlers instead of re-serializing to a String. Removes the second tokenization entirely, so no re-quoting is needed anywhere.
2. Single quoting authority — if the string round-trip must stay, make re-quoting a property of the router's serialization step rather than something each caller remembers, so a new flag is protected by default.
3. Guard the invariant with a test that reproduces the real handler contract (see below) — cheapest, but only catches known paths.

Option 1 also retires quoteIfNeeded / _requoteIfNeeded / the handlers' private _tokenize copies, which currently duplicate near-identical quote logic in three places.

Acceptance tests

Verifiable criteria for whichever direction is chosen:

1. alter-cli mcp chain.add --json '{"chain_id":100}' returns a decodable envelope, not invalid --json.
2. Nested structures and spaces survive: --json '{"a":[1,2],"b":"x y"}' reaches the handler byte-identical.
3. lending positions-batch --users 0xAAA,0xBBB — first address arrives unmodified (lending positions-batch --users a,b prepends a stray quote to the first address, always failing validation #57 stays fixed).
4. Assertions are made on the payload as received by the handler, not on router output.

Criterion 4 is the one that bites. A mock that does not re-tokenize passes against broken code — verified while writing the regression test for --json: the naive version was green with the bug present.

Regression test available

VISIALIS/phoenix_0#1002 adds the --json case, with a mock replicating McpProxyCommandHandler._tokenize. Fails without the fix (rawJson={chain_id:100}), passes with it, 29/29 in the file.

Environment

• macOS 26.6.1, built from source (dart compile exe bin/cli.dart), CLI + MCP server
• Released alter-cli 1.25.0 unaffected by the --json case

[spouletmathis]

Retest sur build phoenix_0 @ 1918d432d — 19/08/2026

Binaires : alter-cli + alter-mcp compilés localement depuis phoenix_0 @ 1918d432d
(HEAD main, ~90 commits après v1.25.0), dart compile exe, macOS 26.6.1 arm64.
Ce n'est pas le paquet Homebrew 1.25.0.

⚠️ Piège de méthode, à connaître pour les prochains retests : alter-cli mcp <tool> spawn
le binaire alter-mcp du PATH, donc par défaut le Homebrew 1.25.0 et non la build testée.
Il faut passer --mcp-binary <chemin> pour réellement tester la build. Mes premiers essais
tapaient l'ancien serveur sans que rien ne le signale.

⚠️ --version et meta.server_version affichent toujours 1.25.0 sur cette build.
Impossible de rattacher un retour terrain à une révision précise — un bump de version
(ou le SHA dans --version) rendrait les prochains retours traçables.

✅ Corrigé sur cette build

Le cas exact de l'issue passe :

$ alter-cli mcp chain.add --json '{"chain_id":100}' --mcp-binary <build>
→ {"success":false,"error":"chain_already_exists","chain_id":100}

Le payload atteint jsonDecode intact — plus de Error: invalid --json: Unexpected character.

Autres payloads structurels vérifiés, tous OK :

Payload	Résultat
{"chain_id":100}	parsé
{"a":{"b":[1,2]},"s":"x y"} (imbriqué + espace)	parsé
{"query":"lending, spread et positions"} (virgules + espaces)	parsé

Et la variante CLI native du bug #57 :

$ alter-cli lending positions-batch --users 0x1111...,0x2222... --pool 0xFb9b... --network gnosis
→ requested_count: 2, returned_count: 2, resolved_count: 2, missing_count: 0

Plus de guillemet parasite sur la première adresse. Aucune régression observée sur les
flags porteurs de données structurelles.

Je laisse l'issue ouverte : elle traite une classe de bug (la double tokenisation
router → handler), pas seulement ses deux instances. Les symptômes connus sont bien
éteints sur cette build ; c'est à vous de juger si la refonte de forme décrite dans le
ticket reste au programme.

[spouletmathis]

Beta-test build locale — #77 toujours reproductible

Build testée : 5e4eb061d (2026-08-19), 83 commits après v1.25.0, compilée localement
(dart compile exe). Ce n'est pas le paquet Homebrew public — vérifié : token.holders
répond sur cette build et retourne Unknown tool sur le binaire Homebrew 1.25.0.

Commandes rejouées

$BUILD/alter-cli session search --query=gnosis --profile=expert
$BUILD/alter-cli chain search --query=gnosis --profile=expert
$BUILD/alter-cli session search --query="RealToken Detroit Maine" --limit=2 --profile=expert
$BUILD/alter-cli session search gnosis --profile=expert          # forme positionnelle

Sortie observée

# --query=gnosis
Recherche pour "--query=gnosis" activée.
Aucun résultat pour "--query=gnosis".

# chain search --query=gnosis
Recherche "--query=gnosis" dans ChainList...
Aucune chaîne trouvée pour "--query=gnosis".

# --query="RealToken Detroit Maine" --limit=2
Recherche pour "'--query=RealToken Detroit Maine' --limit=2" activée.
Aucun résultat pour "'--query=RealToken Detroit Maine' --limit=2".

# forme positionnelle — seule qui fonctionne
Recherche pour "gnosis" activée.
Chaîne (1)
    100 │ Gnosis — chaîne Gnosis déjà présente dans la session

Verdict : ❌ non résolu

Le flag --query= n'est jamais reconnu : la chaîne littérale "--query=gnosis" devient le
terme de recherche. Avec une valeur contenant des espaces, c'est toute la ligne
d'arguments qui est avalée, --limit=2 compris, comme un seul terme. Seule la forme
positionnelle donne un résultat correct.

Le défaut n'est donc pas limité aux « payloads structurels » : il touche aussi les valeurs
scalaires simples sans espace.

Impact usage

Ici, la surface CLI sert aux scripts de suivi patrimoine RealT (hors sessions MCP
interactives). Toute commande paramétrée par flags est inutilisable : elle ne renvoie pas
d'erreur, elle renvoie zéro résultat, ce qui est indiscernable d'un « rien à signaler »
légitime dans un script. C'est le mode de défaillance le plus coûteux — un script qui
« marche » et ne trouve jamais rien.

Cas de test

# Repro — un flag --query n'est pas parsé, sa forme littérale devient la requête
$BUILD/alter-cli session search --query=gnosis --profile=expert

Reproductible sur build 5e4eb061d, profil chargé comme profil neuf, sans clé API,
chaîne Gnosis provisionnée.

Observé vs attendu

Observé : Recherche pour "--query=gnosis" activée. → 0 résultat
Attendu : Recherche pour "gnosis" activée.        → Chaîne (1) 100 │ Gnosis
Vérité terrain : la forme positionnelle `session search gnosis` retourne bien la chaîne 100

✅ Test d'acceptation

Le correctif est accepté si :

1. session search --query=gnosis retourne le même résultat que session search gnosis
   (au moins la chaîne 100 │ Gnosis).
2. session search --query="RealToken Detroit Maine" recherche exactement
   RealToken Detroit Maine, sans les délimiteurs ni les autres flags dans le terme.
3. --limit=2 est interprété comme une limite, pas comme une partie de la requête.
4. Un flag inconnu (--nawak=1) produit une erreur explicite, pas un terme de recherche.
5. Anti-régression : la forme positionnelle session search gnosis continue de fonctionner.

Réserves

Testé sur session search et chain search. Les autres sous-commandes à flags
(lending events --events ..., --users ...) n'ont pas été rejouées une par une ; vu que
lending pool-snapshot --network=... --pool-address=... fonctionne, le défaut semble
propre aux commandes de recherche qui acceptent un terme libre — à confirmer côté code.

[spouletmathis]

Retest — build 31076cc86 : toujours présent, mais la cause est bornée à un seul caractère

Build compilée depuis phoenix_0 HEAD 31076cc86 (v1.25.0 +94 commits),
testée via --mcp-binary.

Ce que j'ai cherché

Mon suivi projet décrivait ce bug comme corrompant « les payloads structurels »
— formulation trop large, héritée de la régression 16b841339. J'ai balayé
9 formes de payload pour délimiter la classe réellement affectée.

for P in <payloads ci-dessous>; do
  $BUILD/alter-cli mcp capabilities.search --json "$P" --mcp-binary $BUILD/alter-mcp --timeout 40
done

Observé

Payload	Résultat
{"query":"simple"}	✅ parsé
{"query":"a, b"} (virgule)	✅ parsé
{"query":"a b"} (espace)	✅ parsé
{"query":"a=b"}	✅ parsé
{"query":"[x]"}	✅ parsé
{"query":"a\\b"} (backslash)	✅ parsé
{"query":"café"} (accent)	✅ parsé
{"query":"a'b"} (apostrophe)	✅ parsé
{"query":"a\"b"} (guillemet échappé)	❌ Error: invalid --json: Unexpected character

Objets imbriqués et listes passent également :
{"a":{"b":[1,2]},"s":"x y"} est parsé (rejeté ensuite sur Unknown parameter(s), ce qui prouve que le JSON a bien été décodé).

Verdict : ⚠️ ouvert, portée plus étroite qu'annoncé

Le défaut ne se déclenche que sur un guillemet double échappé à l'intérieur
d'une valeur string. Ce n'est pas une corruption générale des payloads
structurels.

Ce n'est pas une régression de cette build : la 1.25.0 installée échoue à
l'identique sur le même payload.

alter-cli mcp capabilities.search --json '{"query":"a\"b"}' --timeout 40
# → Error: invalid --json: Unexpected character

Rectification de ma part

Je corrige ce que j'avais laissé entendre côté RMM : j'avais classé ce bug comme
affectant « toute la voie run_alter() ». C'est faux, et il vaut mieux le dire
que de laisser un fil orienter vers une refonte du parsing d'arguments.

Impact RMM : nul. lib/alter.py sérialise via json.dumps() puis passe le
payload à subprocess.run() sous forme de liste d'arguments — pas de shell,
donc pas de re-quoting. Et aucun payload du projet ne contient de guillemet :
uniquement des adresses hex, des numéros de blocs, des noms de réseau et des
noms d'events.

La priorité de cette issue est donc, de mon point de vue de consommateur, plus
basse que je ne l'avais suggéré.

Test d'acceptation

✅ Corrigé si :
   1. capabilities.search --json '{"query":"a\"b"}' est parsé sans erreur
      (rejet ultérieur sur paramètre inconnu = acceptable, le JSON a été décodé)
   2. anti-régression : les 8 autres formes du tableau ci-dessus restent parsées
   3. un payload à guillemets imbriqués sur 2 niveaux
      — {"a":{"note":"il a dit \"oui\""}} — est décodé à l'identique

Réserves

Testé uniquement via le pont CLI (alter-cli mcp ... --json). Je n'ai pas
rejoué ces payloads en session MCP directe, où le comportement peut différer
(c'était le cas pour #72).

Je ne clos pas l'issue.

[spouletmathis]

Beta-test build locale — symptômes toujours éteints, et rectification de mon commentaire du 19/08

Build testée : 31076cc86 (2026-08-20), 94 commits après v1.25.0, dart compile exe,
macOS 26.6.1 arm64. Pas le Homebrew 1.25.0 (vérifié via token.holders).

🔴 Rectification : mon second commentaire du 19/08 est faux

J'avais écrit « #77 toujours reproductible » en m'appuyant sur ceci :

$BUILD/alter-cli session search --query=gnosis --profile=expert
→ Recherche pour "--query=gnosis" activée.
  Aucun résultat pour "--query=gnosis".

J'en avais conclu à une corruption d'argument par double tokenisation. C'est une erreur de
diagnostic de ma part : session search attend une requête positionnelle, et
--query=… n'est pas un flag reconnu par cette sous-commande — la chaîne littérale
--query=gnosis est donc traitée comme le terme recherché. Le comportement observé est
cohérent avec ça, et n'a rien à voir avec la double tokenisation. Je n'aurais pas dû
présenter ce cas comme une reproduction.

Je le signale explicitement pour ne pas laisser le fil orienter le diagnostic dans la
mauvaise direction — c'est plus coûteux que le bug d'origine.

Les 3 critères d'acceptation de l'issue passent

# 1. --json simple
$BUILD/alter-cli mcp chain.add --json '{"chain_id":100}' --mcp-binary $BUILD/alter-mcp
→ enveloppe décodable (chain_already_exists) — plus de "invalid --json"

# 2. imbriqué + espaces + virgules
$BUILD/alter-cli mcp capabilities.search \
  --json '{"query":"lending, spread et positions"}' --mcp-binary $BUILD/alter-mcp
→ payload parsé, réponse normale

# 3. bug #57 — première adresse d'une liste --users
$BUILD/alter-cli lending positions-batch \
  --users 0x15ED1e0c61Ca2fbB98b0ad2F6eD549fE0ee175c7,0x14cCD6FB7C6D5693969F38C8eF5C08d77d260Ce4 \
  --pool 0xFb9b496519fCa8473fba1af0850B6B8F476BFdB3 --network gnosis \
  --mcp-binary $BUILD/alter-mcp --profile=expert
→ requested=2 returned=2 resolved=2 missing=0
  user_address=0x15ed1e0c… HF=0.9855 collat=80965.89 debt=57509.68
  user_address=0x14ccd6fb… HF=0.9816 collat=24187.79 debt=17249.72

Pas de guillemet parasite, pas de payload corrompu. Les données remontées correspondent à
nos positions réelles, ce qui confirme que les adresses arrivent intactes jusqu'au handler.

Payloads structurels supplémentaires vérifiés sur cette build, tous OK : objets imbriqués
avec tableaux, chaînes contenant espaces et virgules, listes d'adresses en --users,
--json volumineux (tokens + valuation_policy imbriqués sur address.statement).

Verdict : ✅ sur les symptômes — la classe de bug reste votre appel

Aucune régression observée sur les flags porteurs de données structurelles, sur ~40 appels
CLI et MCP au cours de ce beta-test.

Comme dit le 19/08, l'issue traite une classe de bug (double tokenisation router →
handler), pas seulement ses instances. Je n'ai pas de nouvel élément à apporter sur la
refonte de forme (option 1 : garder List<String> de bout en bout) — c'est un arbitrage
interne. Le critère 4 de l'issue (asserter sur le payload tel que reçu par le handler)
reste le point qui me semble décisif, puisqu'un mock qui ne re-tokenise pas passe au vert
avec le bug présent.

Un piège de méthode qui mérite d'être documenté

Différent de cette issue, mais de la même famille « ce qui arrive au handler n'est pas ce
qu'on croit » : --mcp-binary est nécessaire aussi sur les commandes CLI natives, pas
seulement sur alter-cli mcp <tool>. Sans lui, alter-cli lending pool-snapshot délègue au
alter-mcp du PATH — donc au Homebrew installé — et reproduit fidèlement des bugs déjà
corrigés dans la build, sans aucun message. Ça m'a fait conclure à tort à une divergence
MCP/CLI sur #73 avant que je ne recoupe.

Un --version portant le SHA de build (aujourd'hui 1.25.0 sur les deux, comme
meta.server_version) supprimerait toute cette classe d'erreur de mesure, et rendrait les
retours de beta-test traçables à une révision.

Impact usage

alter-cli mcp est le point d'entrée scripté de ce projet : la régression --json avait
mis hors service tous les appels non interactifs d'un coup. C'est réparé et stable sur ~40
appels. Le risque résiduel est celui décrit dans l'issue — le prochain flag porteur de
données structurelles repart du même pied.

Réserves

Profil chargé, Gnosis provisionnée, sans clé API explorer. Je n'ai pas testé de payload
contenant des guillemets échappés à l'intérieur d'une valeur JSON ({"note":"il a dit \"oui\""}), qui serait le cas limite le plus dur pour une double tokenisation.

[spouletmathis]

Beta-test build locale — ✅ toujours corrigé (anti-régression)

Build testée : d5126afb0 (2026-08-21). Pas le Homebrew 1.25.0.

Les 3 critères de l'issue passent encore :

1. --json '{"chain_id":100}' → enveloppe décodable chain_already_exists (plus de invalid --json)
2. --json '{"query":"lending, spread et positions"}' → payload parsé, réponse normale
3. lending positions-batch --users addr1,addr2 → requested_count=2 returned_count=2,
   première adresse intacte :
   0x15ed1e0c… HF=0.9852 collat=80965.89 debt=57527.10
0x14ccd6fb… HF=0.9813 collat=24187.79 debt=17254.40

session search gnosis (positionnel) trouve la chaîne. session search --query=gnosis
cherche le littéral --query=gnosis — ce n'est pas une double tokenisation,
c'est un flag inexistant traité comme terme (rectification du 20/08 toujours vraie).

Verdict : ✅ livré

[spouletmathis]

Beta-test build c27f34c38 — ✅ toujours corrigé (anti-régression)

Build testée : phoenix_0 HEAD c27f34c38 (2026-08-21). Pas le Homebrew 1.25.0.

Les 3 critères de l'issue passent encore :

1. --json '{"chain_id":100}' → enveloppe décodable chain_already_exists (plus de invalid --json)
2. --json '{"query":"lending, spread et positions"}' → payload parsé, réponse normale (catalogue métier vide + hint, pas une erreur de parse)
3. lending positions-batch --users addr1,addr2 → requested_count=2 returned_count=2,
   première adresse intacte :
   0x15ed1e0c… HF=0.9851 collat=80965.89 debt=57535.28
0x14ccd6fb… HF=0.9812 collat=24187.79 debt=17255.81

session search gnosis (positionnel) trouve la chaîne via MCP JSON. session search --query=gnosis cherche le littéral --query=gnosis — ce n'est pas une double tokenisation, c'est un flag inexistant traité comme terme (rectification du 20/08 toujours vraie).

Verdict : ✅ livré

[spouletmathis]

Beta-test build locale — ⚠️ inchangé : seul le guillemet échappé casse encore

Build testée : c27f34c38 (v1.25.0 +105 commits), dart compile exe, --mcp-binary. Pas le Homebrew 1.25.0.

Aucun commit de cette build ne retouche le routeur / tokenizer.

Commande rejouée

$BUILD/alter-cli mcp capabilities.search --json '{"query":"a\\"b"}' \
  --mcp-binary $BUILD/alter-mcp --timeout 40

Observé

{"query":"a\"b"}  → Error: invalid --json: Unexpected character  rc=2
objets imbriqués, listes, virgules, espaces, chain_id  → parsés (garde-fou n°1 OK)
Identique à la 1.25.0 installée (pas une régression de cette build)

Verdict

⚠️ ouvert, cause bornée au guillemet échappé à l'intérieur d'une string JSON. Priorité basse.

Impact pipeline

Nul. lib/alter.py sérialise via json.dumps() et passe le payload à subprocess.run() en liste d'arguments (pas de shell, pas de re-quoting). Aucun payload du projet ne contient de guillemet — seulement des adresses, des blocs, des noms de réseau.

Toute la voie run_alter() n'est pas cassée (rectification déjà faite le 20/08). Le garde-fou --json du beta-test reste en tête de checklist : une 1.26.0 qui régresserait au-delà du guillemet échappé casserait tous les skills d'un coup.

Test d'acceptation (rappel)

✅ #77 est levé si {"query":"a\"b"} est accepté (capabilities.search
   rend du JSON, pas invalid --json)
   ET les 3 payloads structurels du garde-fou (objets imbriqués,
   "lending, spread", chain_id) restent parsés

Réserves

Je ne close pas. Non retesté : flags CLI --profile=expert avec JSON dans un argument nommé.