[vraspar]

What

The CLI pays the router's quoted fee, capped at $0.003, sends every routing call to the paid route, and deposits about 5 cents at a time. Based on main, and merges on its own, first. It was split out of #532 at review and needs nothing from the tolerant contract.

• The quoted fee, under a ceiling. The router's 402 is the only price. RoutingPayer pays it at or below ROUTING_FEE_CEILING_ATOMIC ($0.003, what every install agreed to), inside the SDK's per-payment cap, the deposit cap and the spend limits. A quote above it is skipped as fee_above_ceiling, with one notice per session.
  • The ceiling applies only to the configured router's paid route: routeFor(baseUrl) refuses any other origin or path and blocks redirects. Provider 402s go through runPay against their spec price.
  • No payee and no exact price is pinned. A charge below the quote (the server's planned $0.001 charge) is the SDK's to record.
• Deposits of about 5 cents, never $0.25. A deposit is the router's suggested amount (the 402's extra.minDeposit: $0.03 from today's production, $0.05 once the router's update ships), less if the wallet or the per-call limit is smaller, at least ten fees ($0.03 at the ceiling) and at most the SDK's $0.25 cap (fee.ts routingDepositAtomic). It replaces the rule that signed $0.25 from any wallet holding $0.50. A wallet below the deposit is wallet_low, and tenjin doctor uses the same $0.03 floor.
• The spend question names the ceiling and the payer address: "…pays a quoted fee, at most $0.003, from funds set aside (the router's suggested amount, up to $0.25 at a time) and names your wallet address…". The install disclosure names the wallet address too.
• One routing path. requestDecision makes exactly one request, to the paid route. A skipped payment is a skip with the once-per-session notice, never a second request.
  • Deleted: the free-path fallback, freePath, the paid-path-absent memo, the payer's 404 branch, FEE_REQUIRED/isFeeRequired and the tool's ask-twice retry.
  • tenjin hook <kind> keeps a stub that tells the person once per session to ask their agent to set Tenjin up again (updating Claude Code or Codex first if needed).
• tenjin doctor checks the paid route. One warm POST to /route:
  • a 402 is live, and a quote above the ceiling warns;
  • a 200 (fee off) or a 400 (a server without warm) passes;
  • a 404 or 5xx fails.
    The paywall answers 402 before reading the body, so this works on today's production. A local dev server on tenjin main with the fee off reads as failed until the server change that adds the warm form lands.

Checks

• Rebuilt on main (9a6e1f7): typecheck, eslint and prettier pass, and vitest run passes on the 25 changed test files plus both suite-wide consistency tests (26 files, 1,368 tests).
• Deposit sizing (8a7af5f, 27a3ced): vitest run passes on the 25 changed test files (1,364 tests). Putting back the old wallet_low check fails two sizing cases.
• Today's production 402 carries extra.minDeposit: "30000", so this build's first deposit there is $0.03.
• Before the rebuild, end to end against a local router with the warm form and the fee off: tenjin doctor passed its paid-route check with one warm POST.
• CI green (runs now that this targets main)

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no new blocking issue was established.

Summary

The CLI pays the router’s quoted fee up to $0.003 and sends routing decisions only to the paid route.

• The payer follows the router’s quote, up to $0.003 per call.
• Routing decisions use one paid route and never retry for free.
• Older command-style hooks now ask the person to set Tenjin up again.
• tenjin doctor checks whether the paid route can answer.
• Tenjin’s spend and install messages explain the quoted fee and wallet address.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Hook or request tool] --> B[Paid routing route]
  B --> C{Router asks for payment?}
  C -->|No| D[Read decision]
  C -->|Yes| E{Quote within ceiling and limits?}
  E -->|No| F[Skip routing; use native tools]
  E -->|Yes| G[Pay through routing channel]
  G --> D

Loading

_{Reviews (6) · Last reviewed commit: "Merge main (tolerant contract, CLI side)..." · Reviewed by Greptile}

[A1igator]

Review at a6fef25 (layer over #532 at 23a8ad9): 0 blocking, 2 should fix, 0 nits

Should fix

1. The PR body references the private repositories five times (BackTrackCo/tenjin-notes#43, BackTrackCo/tenjin#1046, #1026, #1050, #1052), which this public repository's rule forbids: each reference publishes a private PR number and creates a cross-repo backlink. Replace them with plain words (the plan this is part of; the server changes that charge under the quote and add the warm form) and keep #532, which is this repository's own. #534
2. STALE_HOOK_LINE hands a terminal command to the person: it is shown in the harness's systemMessage to whoever is typing, and the operator's rule is that person-facing text never hands a person a command (it says "ask your agent to ..."). Reword it to tell the person to ask their agent to set Tenjin up again, and let the changeset and the tenjin hook help text follow.

   tenjin-agent/src/router/hook-command.ts

   Line 43 in a6fef25

   export const STALE_HOOK_LINE =

Nothing else I would hold the code on: a skipped payment makes no second request on any route (the Codex hook log pins one route unpaid line), routeFor refuses any URL off the configured router's origin and paid path before anything is sent so a provider's 402 never meets the ceiling, quoteOf takes the largest routing offer at or below $0.003 and routingPolicy offers the SDK only those, a charge below the quote is left to the SDK and tested, the doctor probe's warm POST maps 402 (quote read, above-ceiling warns), 200, 400 and 429 to live and 404 and 5xx to failed, and the hook chunk graph stays free of the SDK (dist-chunks passes on a fresh build since routing-quote is loaded only on a 402). The current plugins run mcp_tool legs, so the stub only meets a copy from an older build. Typecheck, eslint and the touched test files pass locally.

[aether-agent]

_{🤖 Reviewer · Review PR #534: feat(router): pay the quoted routing fee under a $0.003 ceiling,… · claude-code · claude-opus-5-5}

Deep review of a6fef25 against base 23a8ad9 (48 files, 1,994 changed lines). The review used a context pack, 12 line auditors plus 2 catch-up auditors, 11 file owners and 6 independent reviewers, then verifiers. A coverage script confirmed that every changed and context line is in a ledger, so no lines were left unaudited.

Verdict. The money paths hold up:

• quoteOf and routingPolicy agree, so the SDK can only pick an offer at or below the amount feeRefusal checked.
• The routeFor origin/path guard builds its URL the same way as requestDecision, and the call runs with blockRedirects.
• A quote above the ceiling is refused before unlock.
• The SDK's corrective-402 retry reuses the first 402's requirements (@x402/fetch index.mjs:69), so the amount can't be raised mid-call.

The two p2s are about what the person is told:

• On older Claude Code, the new stale-hook line sends them to tenjin install, which can't fix it there.
• The install disclosure leaves out the wallet address that the spend question now names.

The rest are nits: comments or messages made untrue by the switch to a floating quote, and a few edge behaviours.

Leads. eslint (repo config) is clean on the changed files. semgrep p/default and p/security-audit had one hit (bidi characters, tool.test.ts:2554). It is not within three lines of a change, so I dropped it.

Single-source, not confirmed (not posted inline)

• src/router/routing-payer.ts:609-619: the 402 body is left undrained when askFirst refuses. The base had the same pattern for its other refusals; this PR adds the fee_above_ceiling exit. Whether it really keeps sockets out of the pool is unverified.

Refuted or out of scope (dropped)

• Per-call limit not re-checked on a corrective 402. Refuted: the SDK retries with createPaymentPayload(paymentRequired) from the first 402.
• docs/safety-model.md:23 "same limits". Refuted: the day's budget binds through the reserved deposit.
• Fixed $0.03 CHANNEL_DEPOSIT_ATOMIC against a floating hint in eligibility/doctor. Already true at the base.
• src/router/fixtures/README.md fee_required. It describes the server's free route, which is still accurate.
• docs/agent-permissions.md:125-126 "five files" and "docs fetch" background process. Stale since before this PR.

Test gaps

• src/commands/update.test.ts:191: not.toContain('Routing costs') can no longer fail, because ROUTING_FEE_TERMS now starts "Tenjin charges…".
• hooks-fee.test.ts:
  • The deposit-line check (≈199) uses the default quote, which equals the ceiling, so it can't tell route.fee() from the constant.
  • No hook-leg case for a quote above the ceiling (≈222-281).
  • The not POST /api/x402-router busy-channel assertion (≈216) is vacuous now.
• tool.test.ts: no case where RouteSkipped(FEE_ABOVE_CEILING, { quotedAtomic }) reaches the agent text.
• Doctor: a warn probe clearing the unreachable memo (doctor.ts:329) is untested.
• hooks-backoff.test.ts: the 5xx test's memo assertion can't fail, because a skip returns before the memo code.
• routing-payer.test.ts:
  • unpaidWhy returns undefined for a failed outcome too.
  • The refused-URL test doesn't assert the reason.
  • The two-offer test doesn't assert route.fee().
• fee.test.ts: EXPECTED lacks fee_above_ceiling, and the comment at :93 says notices name "no fee amount".
• No fake router can simulate a server missing /route (404) any more.
• Stale test names or comments:
  • reachability.test.ts:84 "empty body"
  • hooks.test.ts:808-812
  • codex-paid-hooks.test.ts:192
  • mcp.test.ts:1075

[aether-agent]

_{🤖 Reviewer · Review PR #534: feat(router): pay the quoted routing fee under a $0.003 ceiling,… · claude-code · claude-opus-5-5}

Re-review of a6fef25..3343ea8. Both p2s are resolved, and so are 15 of the 19 nits. I found nothing new.

p2s, resolved

• Stale-hook loop (hook-command.ts:43): the line no longer hands the person a command. It now says to ask the agent to set Tenjin up again, updating Claude Code or Codex first if needed. Below the floor, install's deferred notice already names claude update, so the advice now leads somewhere. The "keeps routing" wording is gone from all four places: install's deferred reason, notices and steps; doctor's migration and plugin rows; and docs/agent-permissions.md:137, which now says the old tenjin hook command entries no longer route.
• Disclosure (install.ts:111): it now names the wallet address beside the session id.

Nits, resolved

• The spend question is 366 characters, under the base's 371. I measured it with npx tsx at this head.
• An answered skip now ends the backoff. call.answered is set after the first response of any status and carried on every RouteSkipped thrown after it, including no_payer. The hook leg clears the memo. The updated 5xx test writes an expired memo, which readRouterMemo ignores but does not delete, so its readdir assertion would fail without the fix.
• tool.ts uses the lasting-reason nextStep again.
• install prints a warn router check as itself, not as "did not answer".
• The deposit line names the ceiling, and DecisionRoute.fee is gone.
• Doctor's fee row and the comment at :328 are reworded.
• "Small flat fee" is replaced in mcp.ts, README and the docs.
• The changeset, the "once per session" doc line and the fixed $0.03 deposit are reworded.
• The gate.ts comment's numbers hold: 5 − 3.5 = 1.5 s, and DEPOSIT_GATE_TIMEOUT_MS 4.5 s leaves 0.5 s.
• The warm comment and the hook-leg docstrings are reworded.
• The shared marker is now documented as intended.
• update.test.ts now asserts against ROUTING_FEE_TERMS.

Still open, unchanged and with no reply (all nits; the original threads stand)

• hooks.ts:1692: a fee-off decided call can still print "Tenjin wallet unlocked."
• hooks.ts:1685: a fee_above_ceiling marker is never released.
• fee.ts:88: a "0" quote still passes feeRefusal under a zero budget.
• status.ts:149: "at least N calls".

Checks I recorded at this head: npx vitest run src/router src/commands/update.test.ts passed (1733 tests), and npm run typecheck passed.

[aether-agent]

_{🤖 Reviewer · Review PR #534: feat(router): pay the quoted routing fee under a $0.003 ceiling,… · claude-code · claude-opus-5-5}

Re-review of ee3eefb..0e7284b, which edits only .changeset/pre/sdk-routing-deposit.md.

Resolved: the changeset nit at fee.ts:35. The routing-deposit note now says a small wallet sets aside "the router's suggested amount, $0.05 today, and keeps routing until it drops below that". That matches CHANNEL_DEPOSIT_ATOMIC and the payer, which sizes from the live hint. Dropping the "once every 83 calls" and "about every 10 calls" counts is right, since those assumed the old fixed fee.

One correction to my earlier comment: I called this note already released. It is not in CHANGELOG.md, so it is still pending, and editing it is the right fix.

Still open: the fee.test.ts:50 nit (the alignment test only checks that the SDK echoes an explicit hint). It is untouched and does not block.

The diff is release-note text only, so I ran no new checks. The router tests and typecheck I recorded at ee3eefb cover the code, which is unchanged.

[aether-agent]

_{🤖 Reviewer · Review PR #534: feat(router): pay the quoted routing fee under a $0.003 ceiling,… · claude-code · claude-opus-5-5}

Re-review of 0e7284b..3cc1893, a one-line test rename in src/router/fee.test.ts.

Resolved: the fee.test.ts:50 nit. The test is now named "pins the constant to the router's announced $0.05 hint (extra.minDeposit 50000)", which matches what it checks.

All findings from my reviews of this PR's later heads are now resolved. The diff changes only a test title, so I ran no new checks; the router tests and typecheck I recorded at ee3eefb still cover the code, which is unchanged.

[A1igator]

Re-review at 3cc1893: nothing left I would block on.

Round 3, layer over #532 at 23a8ad9. Delta since round 2 (3343ea8): CHANNEL_DEPOSIT_ATOMIC is 50000 and the wallet_low sentence, the README, docs/agent-permissions.md, the deposit test table and the pre-release changeset all say $0.05; the payer still sizes from the 402's extra.minDeposit through the SDK (depositAmountForRequest, which also discards a hint under the quote), with the constant used only where no 402 exists (doctor, the install question, the static wallet_low line). No $0.03 or 30000 reference remains in the layer. Locally at 3cc1893: vitest on the seven touched test files (450 tests) passes.

[A1igator]

Approved again at 3cc1893. The review at this head is clean: the CLI sizes a new channel from the router's $0.05 hint, the wallet floor and the docs agree, and the scoped tests pass locally. CI does not run while the base is a stack branch, so this approval rests on the review and the local runs; the CI rollup evaluates once this PR targets main.

The base branch was changed.

[vraspar]

@A1igator done as you asked on the plan:

• Based on main, alone, and merges first. It needed nothing from feat(router): tolerant contract, CLI side: ignore router fields this CLI doesn't know #532 to work. In code both PRs rewrite, it only borrowed two of feat(router): tolerant contract, CLI side: ignore router fields this CLI doesn't know #532's names. On main, a decided answer carries no skipped offers, and the paid path reads answers with main's readDecision (9a6e1f7).
• Your deposit check: today's server does send a hint, the SDK's default. Production's 402 carries extra.minDeposit: "30000" ($0.03). The old rule here would also have signed $0.25 from any wallet holding $0.50, which the owner ruled out in favour of about 5 cents. 8a7af5f takes the background top-up's sizing: the hint, less if the wallet or the per-call limit is smaller, at least ten fees, at most $0.25. Against today's server that is $0.03, and with the router's $0.05 hint it is $0.05.
• CI runs now. Your approval was on the stacked version, so this needs another look once it is green.

🤖 Generated with Claude Code

[aether-agent]

_{🤖 Reviewer · Review PR #534: feat(router): pay the quoted routing fee under a $0.003 ceiling,… · claude-code · claude-opus-5-5}

Re-review of 3cc1893..27a3ced. This PR now targets main directly instead of #532.

What changed

1. A clean merge of main: hash-wasm (#521) and others. I checked that git merge-tree of the two parents equals the merge commit; that merged code is not reviewed here.
2. 9a6e1f7 drops #532's tolerant contract. Against main, pay.ts, http.ts, choices.ts, jobs.ts and #532's three changesets are now untouched. decision.ts keeps only this PR's one-route change on main's readDecision.
3. 8a7af5f adds a new deposit-sizing rule.
4. 27a3ced is docs only.

I re-emitted the guide because the base and the deposit approach both changed.

The new deposit rule
The deposit is the smallest of three amounts: the 402's minDeposit (or $0.05 when it has none), the wallet balance, and maxAutoSpend. It is never below ten quoted fees, and never above min(SDK cap, $0.25).

• I traced it against the SDK. parseAnnouncedMinDeposit drops a hint below the quote. The SDK's resolveDepositAmount then requires at least minimumDepositAmount and clamps to maxDeposit, both of which routingDepositAtomic already satisfies.
• The router's hint can't push the deposit past the per-call limit or $0.25 (see the confirmed note inline).
• Behaviour change, documented in the commit: a funded wallet now deposits the hint, $0.03 in production today, instead of $0.25. So deposits, which take the longer 4.5 s budget, come about every ten calls instead of every ~83.

One new nit (inline, eligibility-check.ts:148): doctor sizes its deposit from $0.05 while production announces $0.03. With $0.03–$0.05 left in the daily budget, doctor reports a refusal the payer would not make. I reproduced this with npx tsx.

CI

• The Node 22 job (lint, typecheck, build, test, audit) passed at this head.
• The Node 24 job failed one test, codex-paid-hooks.test.ts > show the real reason…, with ENOTEMPTY … rmdir '/tmp/router-codex-paid-*/router' in afterEach.
• That looks like a pre-existing teardown race, not this change. The same error hit a different test in that file on #532's run 40961476849. The router observer's chained, unawaited writeObservation (router-observer.ts:101) can still be writing under router/ when the test's rm runs.
• It passed 6/6 locally on Node 24.22. A rerun should clear it. Awaiting or disposing the observer in server.close() would fix the flake.

Earlier nits: still open from the first review and unchanged:

• hooks.ts:1713: the "unlocked" notice can fire with the fee off.
• The fee_above_ceiling marker is never released.
• fee.ts:108: a zero quote passes under a zero budget.
• status.ts:149: "at least N calls".

None of these blocks.

[A1igator]

Re-review at 27a3ced: nothing left I would block on.

[A1igator]

@vraspar this gets my approval once the two open aether threads are resolved. Round 4 found nothing else to fix, and every check is green on 27a3ced after the re-run. If the head moves before then, I will look at the change first.

[vraspar]

@A1igator both aether threads are resolved. The deposit-rule one is a confirmation with nothing to change. The doctor-sizing nit is declined with its reason in the thread, because the proposed fix would turn into the opposite mismatch once the router announces $0.05. The head is still 27a3ced.

🤖 Generated with Claude Code

[A1igator]

Approved at 27a3ced. Round 4 found nothing to fix, both aether threads are resolved, and every check is green on this head.

[vraspar]

@A1igator I merged main, which now has #532, into this branch at 8b6efca. There were three conflicts, all on lines that #532 and this PR both changed:

• decision.ts: this PR's single paid request stays as it was (no free-path retry, no freePath), and feat(router): tolerant contract, CLI side: ignore router fields this CLI doesn't know #532's skipped offers are added on top. The paid route's answer and a payer's unreached answer both go through readOffer, so requires is checked on each.
• hooks.ts: the import keeps ROUTE_PAID_PATH and adds REQUIRES_UNMET.
• fixtures/README.md: kept this PR's fee paragraph.

Typecheck, lint and the four router test files pass locally (431 tests). The push dismissed your approval, so could you re-approve once CI is green?

🤖 Generated with Claude Code

[aether-agent]

_{🤖 Reviewer · Review PR #534: feat(router): pay the quoted routing fee under a $0.003 ceiling,… · claude-code · claude-opus-5-5}

Re-review at 8b6efca. Since 27a3ced, the only change is a merge of main, which now includes #532 (tolerant contract, CLI side). Compared with main, the PR still changes the same 52 files, so the previous reading guide carries forward.

Merge resolution. git show --remerge-diff shows conflicts in three files, all resolved correctly:

• src/router/decision.ts:
  • DecisionOutcome keeps main's skipped?: SkippedOffer[] on decided and drops freePath. That's correct, since this PR removes the second request to the free route.
  • In the RouteSkipped catch, the payer's unreached answer is now read through readOffer instead of readDecision, so an offer this build can't run is taken out on that path too.
  • The paid answer still goes through readOffer.
  • The free-route reads are as they are on main: browse still uses readDecision, and the tool spec read still uses readOffer.
  • No freePath reference is left anywhere in src.
• src/router/hooks.ts: the import merges both sides (REQUIRES_UNMET, ROUTE_PAID_PATH). Main's skipped-offer warning loop runs on any decided outcome, which covers the paid answer and an unreached answer alike.
• src/router/fixtures/README.md: keeps this PR's fee and ceiling paragraph.

The other files merged without conflicts and match main's #532 content, which I didn't re-review.

Prior findings. Neither file was touched by this push:

• src/router/routing-payer.ts:760: the confirmed note still holds.
• src/router/eligibility-check.ts:148: the doctor-sizing nit is still open. Doctor checks the policy against $0.05, but production's hint is $0.03.

CI. All jobs are green at this head, including Node 24, so the codex-paid-hooks teardown flake from the last head didn't come back. Greptile and Aether Review are still pending.

The four nits from the first review are unchanged and still non-blocking. No new findings.

[A1igator]

Re-review at 8b6efca: nothing left I would block on.

[A1igator]

Approved at 8b6efca. The merge of main keeps both sides of all three conflicts, round 5 found nothing to fix, and every check is green on this head.