kira-wallet 0.1.15 → 0.1.17

package/THIRD_PARTY_NOTICES.md

@@ -47,3 +47,21 @@ per-contract provenance is in the catalog.
 ## Alchemy setup illustration
 
 `viewer/static/alchemy-create-app.png` is an unmodified example screenshot from Alchemy’s public API key walkthrough, used to explain app setup. Source: https://www.alchemy.com/docs/create-an-api-key . The image contains no Kira operator account or credential. Alchemy retains rights to its interface and illustration.
+
+## Market platform marks
+
+The local market cards identify their sources using the official marks retrieved
+on October 19, 2026: [Mint Club app icon](https://mint.club/apple-touch-icon.png),
+[Uniswap logo](https://github.com/Uniswap/interface/blob/main/packages/ui/src/assets/icons/uniswap-logo.svg),
+and [Aerodrome favicon](https://aerodrome.finance/svg/AERO/favicon.svg).
+These marks identify external services and remain their respective owners' marks.
+Kira does not claim affiliation or endorsement. The original files are served
+locally from `viewer/static/venues/`.
+
+## Explorer mark
+
+The Etherscan icon in `viewer/static/explorers/` is used for explorer links.
+Each link retains its destination explorer name or the generic Explorer label.
+It was retrieved unchanged on October 19, 2026 from
+[Etherscan documentation](https://docs.etherscan.io/mintlify-assets/_mintlify/favicons/etherscan/PMbbZQeU1A_1WqNP/_generated/favicon/android-chrome-192x192.png).
+The mark belongs to its owner and does not imply affiliation or endorsement.

package/cashout-quotes.cjs

@@ -25,7 +25,7 @@ function contractRevert(error) {
   }
   return reverted;
 }
-async function quotePool(client,network,token,pool,block,blockHash,deployments,{batchRead}={}) {
+async function quotePool(client,network,token,pool,block,blockHash,deployments,{batchRead,fullOnly=false}={}) {
   const state=pool.factory_measurement?.state||{},balance=integer(token.wallet_balance_raw);
   const unknown=reason=>({status:'unknown',reason,gas_included:false,execution_verified:false});
   if(!balance||!address(token.token_address)||!address(state.token0)||!address(state.token1)||state.token0.toLowerCase()===state.token1.toLowerCase()
@@ -43,7 +43,16 @@ async function quotePool(client,network,token,pool,block,blockHash,deployments,{
   if(canonical('v3')&&quoter&&Number.isInteger(state.fee)&&state.fee>=0&&state.fee<1_000_000) {
     kind='uniswap_v3_quoter';
     request=amount=>({address:quoter.address,abi:v3Abi,functionName:'quoteExactInputSingle',args:[{tokenIn:token.token_address,tokenOut:output,amountIn:amount,fee:state.fee,sqrtPriceLimitX96:0n}]});
-    decode=result=>result[0];
+    decode=result=>{
+      // QuoterV2's default limit is MIN_SQRT_RATIO+1 / MAX_SQRT_RATIO-1
+      // (Uniswap v3-core TickMath). At that boundary input can be unspent.
+      if(fullOnly){
+        const after=integer(result[1]);
+        if(after===null||after<=4295128740n||after>=1461446703485210103287273052203988822378723970341n)
+          throw Error('Full input consumption is not established at the pool price limit');
+      }
+      return result[0];
+    };
   }else if(network.chain_id===8453&&state.factory?.toLowerCase()==='0x420dd381b31aef6683db6b902084cb0ffece40da'&&pool.venue==='aerodrome') {
     kind='aerodrome_pool';
     request=amount=>({address:pool.pool,abi:aeroAbi,functionName:'getAmountOut',args:[amount,token.token_address]});
@@ -54,7 +63,7 @@ async function quotePool(client,network,token,pool,block,blockHash,deployments,{
     kind='uniswap_v2_reserves';quote=async amount=>v2AmountOut(amount,reserveIn,reserveOut);
   }else return unknown('Quote adapter unavailable for this verified pool');
   if(request)quote=async amount=>decode(await client.readContract({...request(amount),blockNumber:block}));
-  const amounts=inputAmounts(balance);let failures=0,buffer=[];
+  const amounts=fullOnly?[balance]:inputAmounts(balance);let failures=0,buffer=[];
   for(let index=0;index<amounts.length;index++) {
     const amount=amounts[index];
     let result;

package/cashout.py

@@ -136,6 +136,7 @@ def classify(token, market, *, environment='mainnet'):
             proceeds = output * Decimal(price['usd'])
         result['quotes'].append({'kind': quote.get('kind'), 'input_amount_raw': str(quote['input_amount_raw']),
                                  'output_amount': format(output, 'f'), 'output_address': quote['output_address'].lower(),
+                                 'output_symbol': quote.get('output_symbol'),
                                  'quoted_output_usd': format(proceeds, 'f'), 'qualifies': proceeds >= Decimal('1'),
                                  'block_number': block, 'block_hash': block_hash, 'observed_at': quote['observed_at'],
                                  'output_price': price, 'partial_input': amount < holding,

package/chain_lifecycle.py

@@ -22,9 +22,9 @@ NOTICES={
         'notice_url':'https://www.alchemy.com/docs/reference/degen-deprecation-notice',
         'network_shutdown_date':None,'provider_support_ended_on':'2026-08-31',
         'note':'Alchemy describes Degen L3 as shut down. Its provider support ended August 31. The exact network shutdown date is not independently established. Base DEGEN is a separate token.'},
-    5112:{'status':'retirement_reported','verified':False,'reviewed_on':REVIEWED_ON,
-        'notice_url':None,'reference_url':'https://docs.ham.fun/',
-        'note':'The operator reports Ham has stopped. A primary closure notice has not been located. Failed reads do not establish closure.'},
+    **{cid:{'status':'retired','verified':False,'confirmation':'operator','reviewed_on':'2026-10-19',
+        'notice_url':None,'note':'Excluded from new research by operator confirmation. Historical observations are preserved; no independent closure notice is claimed.'}
+        for cid in (5112,54176)},
 }
 
 
@@ -32,7 +32,7 @@ def lifecycle(chain_id):
     state=dict(NOTICES.get(chain_id,{'status':'unconfirmed','verified':False,
         'notice_url':None,'note':'No verified retirement notice is recorded. Connectivity and discovery are separate observations.'}))
     state.update(reference_url=REFERENCES.get(chain_id,state.get('reference_url')),
-        reviewed_on=REVIEWED_ON if chain_id in REFERENCES or chain_id in NOTICES else None,
+        reviewed_on=state.get('reviewed_on') or REVIEWED_ON if chain_id in REFERENCES or chain_id in NOTICES else None,
         audit_result='reference_unavailable' if chain_id in UNAVAILABLE_REFERENCES else 'reference_retrieved' if chain_id in REFERENCES else 'notice_reviewed' if chain_id in NOTICES else 'not_reviewed')
     if chain_id==8217:
         state['provider_notice']={'provider':'The Graph','support_ended_on':'2026-08-31','url':'https://docs.kaia.io/build/tools/indexers/','note':'Indexer support ended. This does not establish network retirement.'}
@@ -41,4 +41,4 @@ def lifecycle(chain_id):
 
 def retired(chain_id):
     state=lifecycle(chain_id)
-    return state['status']=='retired' and state['verified'] is True
+    return state['status']=='retired' and (state['verified'] is True or state.get('confirmation')=='operator')

package/docs/AGENT_TOOLS.md

@@ -32,7 +32,7 @@ wallet scope and research permission. It sends no wallet facts. Authentication
 stays with the installed CLI. No desktop tokens or authentication files are copied.
 
 With research enabled, a bounded host-mediated loop provides portfolio_read,
-wallet_read, token_read, snapshots_list, snapshot_read, snapshots_compare,
+wallet_read, token_read, holdings_query, snapshots_list, snapshot_read, snapshots_compare,
 job_list, job_read, holdings_refresh and prices_refresh. Every operation is
 scoped to registered wallets allowed by the conversation. Historical reads use
 normalized financial projections. Unknown values and historical quote times
@@ -104,3 +104,24 @@ rpc_status pending means a network has not yet been researched. It does not
 prove an RPC outage. For a curve comparison, match chain and contract and
 compare reserve, supply, next-mint price and royalty observations. A newer
 block or a different wallet-sized burn quote alone cannot prove curve movement.
+
+## Bounded full-inventory queries
+
+Connected chat uses `holdings_query` for names, rankings and aggregates. Its
+`mode` is `search`, `rank` or `aggregate`. It scans every approved saved position
+on the host and returns at most 25 results per page. This response bound never
+limits holdings discovery. Optional filters include wallet, chain, environment
+and minimum recorded USD value. Exact symbols, names and contracts take
+precedence over substring matches; multiple chain/contract identities remain
+explicitly ambiguous. `group_by: asset` combines the priced subset by identity,
+while `position` keeps each wallet position separate. Unknown and excluded
+positions have independent counts. Ranking cannot create a price for them.
+
+Top-N completion requires a delivered full-inventory ranking receipt, including
+natural requests such as “top five.” Search pages must be delivered through the
+last match before claiming that all matches were read. A host count or sum does
+not require sending every position to the model. These reads never queue jobs.
+The existing 32-read plan, eight-round, prompt/context and time limits remain.
+Detailed internal receipts are kept locally; partial-result messages use plain
+language. Safe absolute HTTP(S) Markdown links are clickable; raw HTML remains
+escaped and images, credential URLs and active URL schemes stay disabled.

package/docs/JOB_CONTRACT.md

@@ -44,10 +44,18 @@ no absolute paths or arbitrary file reads are supported.
 
 The optional `started_at` timestamp records when the current attempt was
 claimed by the worker. Resuming replaces it on the next claim. Older envelopes
-remain valid without it. The viewer then labels its timer "Since request"
-instead of claiming an exact execution time. Terminal timers stop at the last
-recorded update. A queued job uses its latest queue transition, not a previous
-attempt's start.
+remain valid without it. The viewer then labels its active timer "Since request"
+and its terminal timer "Request duration" instead of claiming an exact execution
+time. Terminal attempt and total timers stop at the last recorded event, falling
+back to the saved update time. Total duration includes waiting and pauses across
+attempts. A queued job uses its latest queue transition, not a previous attempt's
+start.
+
+Completed sell analysis leaves the wallet's progress card. An observed transition
+from queued or running to succeeded or partial shows a brief completion notice.
+Loading saved history does not repeat that notice. Activity retains the result,
+unknown checks, stages and stopped timers. Failed, paused and interrupted work
+keeps its recovery controls.
 
 States: queued -> running -> succeeded | partial | failed | cancelled.
 Recovery converts unfinished running jobs to interrupted. Explicit resume may

package/docs/RELEASE.md

@@ -79,7 +79,7 @@ The earlier unpublished 0.1.2 candidate is preserved in the ignored
 `dist/preserved-0.1.2-bad8f02/` directory. Use the current `dist/release.json`
 and its matching archive for publication; do not mix manifests from candidates.
 
-Keep published GitHub tags, release assets and npm versions through 0.1.14
+Keep published GitHub tags, release assets and npm versions through 0.1.16
 immutable. Do not rebuild them from later documentation commits. Future package
 changes need a new version. Release preparation does not publish a GitHub
 release, promote the website or publish to npm.
@@ -95,12 +95,12 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.1.15.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-0.1.17.tgz`. The ignored `dist/release.json` records its source
 commit, SHA-256 and member count. It never publishes. After reviewing that
 manifest, the operator's final command from the project root is:
 
 ```sh
-npm publish ./dist/kira-wallet-0.1.15.tgz --access public
+npm publish ./dist/kira-wallet-0.1.17.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.
@@ -432,3 +432,88 @@ dry-run that exact archive. npm publication remains operator-only. Preserve the
 personal 0.1.14 installation, credentials, paused history and published archives.
 Use a separate private workspace for candidate acceptance. No GitHub release,
 website deployment or personal app upgrade is part of this preparation.
+
+## Published 0.1.16
+
+This version repairs Mint Club symbol routes, including ERC1155 NFT routes and
+encoded symbols, without rewriting historical snapshots. Market lookup attaches
+both pair members and price updates persist new pools. Pool identity preserves
+Uniswap v4 IDs, versions and fee tiers. Visible market records are independent
+from price eligibility and executable proceeds. Existing thin-market, testnet
+and unknown-value protections remain.
+
+The basic market pass supplements Mint Club ERC20 holdings with official
+Uniswap v2/v3/v4 index records and bounded Base common-quote factory reads.
+Provider errors and incomplete pages remain partial. This is not proof of an
+exhaustive blockchain-wide pool inventory. It does not require sell analysis.
+Prior successful market observations survive missing sources; metadata-only
+factory reads cannot refresh the date of an old price or liquidity observation.
+
+Connected AI can search symbols and names, rank the full saved inventory, and
+compute exact filtered aggregates without reading every inventory page into its
+context. Official market marks and token/reserve artwork identify pool cards.
+Ham and OverProtocol are excluded by operator confirmation, distinguished from
+independently verified notices. Historical evidence is preserved. Successful
+price metadata batches are reused for artwork to avoid redundant source reads.
+
+Holdings give markets a separate row, retain every saved pool and open known
+venue destinations directly. Token-title Explorer links use the locally served
+Etherscan mark. Chain selectors show network artwork, sidebar actions align,
+and All tokens adds the same value filters as wallet holdings.
+
+Wallet, All tokens and network lists compare known value with saved sell-out
+estimates. Basic holdings and explicit price refreshes collect bounded direct
+pool quotes without viewer-triggered RPC reads or additional route discovery.
+Uniswap v2/v3 and Base Aerodrome classic pools are supported. Full-balance
+quantities are checked at the quote block. Unknown, unsupported, changed-input,
+testnet and archived positions cannot become a USD sale estimate. Output-price
+and quote clocks remain distinct. Independent quotes sharing liquidity are not
+summed into portfolio proceeds; gas and execution guarantees remain excluded.
+
+The wallet header separates identity, holdings status, valuation and optional
+sell analysis. New wallets can show progress before their first snapshot. A
+retired-network catalog mismatch no longer stops new holdings jobs. Failed work
+offers typed recovery guidance and preserves prior results and failure history.
+Completed sell analysis dismisses its progress card and briefly announces saved
+results. Activity retains stages, unresolved checks and durations frozen at the
+terminal event. Paused, interrupted and failed work retains recovery actions.
+
+Imported wallets and autonomous execution are deferred to post-MVP. The decision
+and reconsideration conditions are recorded in [wallet capabilities](WALLET_CAPABILITIES.md).
+This release adds no transaction signing, token approval or trading capability.
+
+Release acceptance covers the repository suite, clean installation, source and
+history privacy checks, exact archive membership, real unchanged natural-language
+questions and responsive market interactions. Review not selected. Publication
+remains operator-only. A feature-branch candidate is not a merged release or a
+published package; the final manifest must identify the accepted source commit.
+The final 0.1.16 archive was frozen from landed source. Superseded unpublished
+candidates are preserved. Only the archive matching its final manifest was a
+publication target.
+
+The operator published 0.1.16 on October 20, 2026. Its registry archive matched
+the frozen manifest and all 101 installed package members. Live acceptance
+found the agent-context omission addressed in 0.1.17 below. The published
+archive remains immutable.
+
+## Release candidate: 0.1.17
+
+After a price refresh saved a full-balance DEX quote, chat could report that no
+estimate existed while the UI displayed it. Detailed agent facts now include
+the same validated `sell_out` projection used by the UI. Compact holdings pages
+retain quote presence and defer the detailed output to a scoped token read.
+The separate legacy Mint Club burn field does not represent every sale route.
+
+Output amounts, quote and price observation times, reference valuations, gas
+exclusions and execution caveats stay intact. Wrong-wallet caches, partial
+inputs and testnet positions remain excluded. Independent wallet estimates
+sharing liquidity cannot be added into portfolio proceeds. This change adds
+no provider calls or quote calculations.
+
+Acceptance includes the full repository suite, clean installation, tracked and
+history privacy checks, and exact archive membership. An isolated exact package
+using the same saved records, model settings, prior conversation and unchanged
+question returned the recorded DEX output and reference valuation without
+starting provider jobs. Product acceptance applies only to identical product
+bytes. Review not selected. Freeze the final archive from the landed source
+and dry-run that archive. npm publication remains operator-only.

package/docs/WALLET_CAPABILITIES.md

@@ -1,5 +1,70 @@
 # Wallet capability direction
 
+## Post-MVP decision: Imported wallets and execution, 2026-10-19
+
+The operator accepted deferring the proposed Imported wallet execution stack
+after the architecture, dependency and security discussion. It is post-MVP
+research, not an implementation ticket or permission to request wallet grants.
+This decision supersedes any earlier suggestion to begin a three-group rollout.
+
+Keep the current Watching and OWS experiences for the MVP. External browser
+connections remain public-address sources for Watching wallets. Existing
+human-submitted encrypted OWS creation and public-descriptor connection are
+implemented; transaction signing, transfers and trading are not implemented.
+Do not add a third wallet group before its distinct capability is approved.
+
+The evaluated future groups are Watching wallet, OWS wallet and Imported wallet.
+For this proposal, Imported means connecting an existing external account and
+explicit execution permissions while retaining its original keys in that wallet.
+It does not mean importing a seed phrase or private key into Kira. Keep account
+origin separate from execution capability. A future conversion must preserve the
+same account's holdings and history without double-counting the portfolio.
+
+The recommendation is to defer autonomous execution. Dependency size can be
+bounded, but grant enforcement, signer isolation, transaction validation, nonce
+ownership, duplicate prevention, revocation and uncertain-result recovery create
+substantial security and maintenance obligations. Saved sell-out estimates are
+research evidence and cannot be treated as ready-to-submit transactions.
+
+A metadata-only dependency experiment using Smart Accounts Kit 2.0.0 increased
+the lockfile package entries, excluding the root, from 18 to 53. Existing package
+versions did not change. The SDK's own reported unpacked size was 3,156,894 bytes,
+excluding its dependencies. This is not a browser bundle, memory or runtime
+benchmark. No SDK was installed in the project and no signing code was run.
+
+Reconsider only after a concrete recurring action justifies execution support:
+
+- Begin with one chain and one supported action, confirmed per transaction in
+  the external wallet. Native key import remains outside this proposal.
+- Consider limited automation later as an optional execution component. Define
+  actual on-chain restrictions for amounts, recipients, contracts and expiry;
+  local application checks alone do not constrain a compromised signing key.
+- Keep private signing material outside model processes, prompts, browser
+  storage, research records and logs. Package or process separation alone is
+  not proof of an effective security boundary.
+- Verify the granted permissions rather than assuming they equal the request.
+  Treat pause, disconnect and confirmed permission revocation as separate states.
+- Validate current balances, exact calldata, fees and minimum output before
+  submission. Recover ambiguous sends without automatic duplicate transactions.
+- Verify expiry, revocation, rejected actions and recovery with synthetic and
+  testnet evidence before considering mainnet. Independent security review is
+  recommended for that future scope and remains operator-selected.
+
+MetaMask Advanced Permissions was a researched candidate, not an operator-selected
+integration. ERC-7715 remains a draft and supported permission types and networks
+must be checked again when this work is scheduled. OWS execution would need the
+same security assessment; its current in-process policy and key handling are not
+an on-chain or hardware isolation guarantee. Review not selected.
+
+Primary references checked on 2026-10-19:
+[ERC-7715](https://eips.ethereum.org/EIPS/eip-7715),
+[EIP-7702 security](https://eips.ethereum.org/EIPS/eip-7702#security-considerations),
+[MetaMask supported permissions](https://docs.metamask.io/smart-accounts-kit/get-started/supported-advanced-permissions/),
+[delegation revocation](https://docs.metamask.io/smart-accounts-kit/guides/delegation/disable-delegation/),
+[OWS key isolation](https://github.com/open-wallet-standard/core/blob/main/docs/05-key-isolation.md).
+
+## Historical design context: 2026-10-04
+
 Agreed with the operator on 2026-10-04: begin with Watching wallet connection.
 Transfers, swaps and OWS Managed wallets need separate design and verification
 before implementation. This is a future direction, not a delivered capability.

package/holdings_query.py

@@ -0,0 +1,74 @@
+"""Bounded results from the complete authorized saved projection, without model paging."""
+from decimal import Decimal, localcontext
+import json
+from kira_jobs import JobError
+
+
+def query_holdings(wallets, args):
+    mode=args['mode'];query=args.get('query','').strip().casefold()
+    if mode not in ('search','rank','aggregate'):raise JobError('invalid_tool','Choose search, rank or aggregate.')
+    if mode=='search' and not query:raise JobError('invalid_tool','Supply a token symbol, name, contract or native.')
+    group_by=args.get('group_by','asset')
+    if group_by not in ('asset','position'):raise JobError('invalid_tool','Group by asset or position.')
+    environment=args.get('environment','mainnet')
+    if environment not in ('mainnet','testnet','all'):raise JobError('invalid_tool','Choose mainnet, testnet or all.')
+    limit=args.get('limit',10);offset=args.get('offset',0)
+    if limit>25:raise JobError('invalid_tool','Use at most 25 query results; this does not limit the scanned inventory.')
+    minimum=Decimal(str(args['minimum_value_usd'])) if 'minimum_value_usd' in args else None
+    def eligible(asset):
+        return not asset.get('archived') and (environment=='all' or asset.get('environment')==environment) and ('chain_id' not in args or asset['chain_id']==args['chain_id'])
+    def exact(asset):
+        return query in {str(asset.get('symbol','')).casefold(),str(asset.get('name','')).casefold(),str(asset.get('address','')).casefold()} or query=='native' and asset.get('is_native')
+    exact_match=bool(query) and any(eligible(a) and exact(a) for w in wallets for a in w['assets'])
+    scanned=0;selected=[];outside=0;unpriced=0
+    for wallet in wallets:
+        for asset in wallet['assets']:
+            scanned+=1
+            if 'chain_id' in args and asset['chain_id']!=args['chain_id']:continue
+            if query and not (exact(asset) if exact_match else query in str(asset.get('name','')).casefold() or query in str(asset.get('symbol','')).casefold()):continue
+            if asset.get('archived') or environment!='all' and asset.get('environment')!=environment:
+                outside+=1;continue
+            value=asset.get('value_usd') if asset.get('environment')=='mainnet' else None
+            if value is None:unpriced+=1
+            if minimum is not None and (value is None or Decimal(str(value))<minimum):continue
+            selected.append((wallet,asset))
+    from kira_agent import recorded_valuation, wallet_facts
+    valuation=recorded_valuation([a for _,a in selected])
+    groups={}
+    for wallet,asset in selected:
+        key=asset['id'] if group_by=='asset' else wallet['address'].lower()+':'+asset['id']
+        groups.setdefault(key,[]).append((wallet,asset))
+    ranked=[]
+    for key,positions in groups.items():
+        values=[Decimal(str(a['value_usd'])) for _,a in positions if a.get('value_usd') is not None and a.get('environment')=='mainnet']
+        with localcontext() as context:
+            context.prec=100;total=sum(values,Decimal(0)) if values else None
+        ranked.append((key,positions,total))
+    if mode=='rank':ranked=[r for r in ranked if r[2] is not None]
+    ranked.sort(key=lambda r:(r[2] is None,-r[2] if r[2] is not None else Decimal(0),r[0]))
+    page=ranked[offset:offset+limit] if mode!='aggregate' else []
+    rows=[];remaining=40000
+    for key,positions,total in page:
+        facts=[]
+        for wallet,asset in positions:
+            fact=wallet_facts([{**wallet,'assets':[asset]}],pool_budget=max(0,remaining))[0]['assets'][0]
+            remaining-=len(json.dumps(fact.get('pools',[])).encode())
+            facts.append({'wallet':wallet['address'],'wallet_name':wallet['name'],'snapshot_id':wallet.get('snapshot_id'),'asset':fact})
+        rows.append({'identity':positions[0][1]['id'],'value_usd':format(total,'f') if total is not None else None,
+                     'position_count':len(positions),'unpriced_position_count':len(positions)-sum(a.get('value_usd') is not None and a.get('environment')=='mainnet' for _,a in positions),
+                     'positions':facts})
+    count=len(ranked)
+    response={'mode':mode,'match_type':'exact' if exact_match else 'substring' if query else 'all','group_by':group_by,'environment':environment,'scanned_position_count':scanned,
+              'matched_position_count':len(selected),'matched_asset_count':len({a['id'] for _,a in selected}),
+              'unpriced_position_count':unpriced,'outside_scope_count':outside,'valuation':valuation,
+              'result_count':count,'results':rows,'offset':offset,'next_offset':offset+len(rows) if mode!='aggregate' and offset+len(rows)<count else None,
+              'ambiguous':mode=='search' and len({a['id'] for _,a in selected})>1,
+              'query_scope':{'mode':mode,'full_inventory_scanned':True,'requested_limit':limit,'offset':offset,'result_count':count},
+              'note':'Exact query over approved saved holdings, including records beyond the first page. Ranking sums the priced mainnet subset per chain and contract; unknown values remain separate. Not live wealth or sale proceeds. Search may match multiple identities; report the ambiguity rather than guessing. Missing records are unknown.'}
+    # Never enlarge the native context to accommodate a pathological result.
+    while len(json.dumps(response,ensure_ascii=False).encode())>120000 and rows:
+        rows.pop();response['next_offset']=offset+len(rows)
+    if mode!='aggregate' and page and not rows:raise JobError('context_limit','This match exceeds the detail limit. Use a wallet filter or token_read.')
+    response['query_scope']['returned_count']=len(rows)
+    response['query_scope']['complete']=mode=='aggregate' or len(rows)==len(page)
+    return response

package/kira_agent.py

@@ -30,8 +30,10 @@ SYSTEM = ('You are Kira, a careful wallet research partner. Answer in the langua
     'The current recorded context supersedes older facts in the conversation. '
     'A bounded summary is not contradictory new evidence. pools_omitted means recorded pool details were left out of this response, not absent from the record. '
     'Use token_read before judging or retracting market details when pools are omitted. Testnet assets are excluded from portfolio valuation; do not infer a zero market price. '
+    'Use holdings_query search for token names or symbols, rank for top-N, and aggregate for counts and sums. These scan every approved saved holding on the host and return bounded results. Never page through inventories for ranking, counting or named-token questions. Use one search per named token, optionally chain-filtered. Report same-symbol ambiguity with chain and contract. Rank group_by asset combines the priced subset by identity; group_by position ranks wallet positions. Unknown prices are excluded from ranks and counted separately. '
     'assets_omitted and next_offset describe a page, not missing holdings. Use wallet_read with offset and limit for more holdings, and token_read for detailed evidence. '
-    'Compact pages defer exit_quote and curve details. exit_quote_recorded true means a validated historical quote exists in the record even if its output is omitted here. Use token_read before judging execution evidence or claiming that a quote is absent. False means no validated quote in this snapshot, not that no exit route exists. '
+    'Compact pages defer sell_out, exit_quote and curve details. exit_quote_recorded true means a validated saved full-balance quote exists, including cached DEX quotes, even if its output is omitted here. Use token_read before judging execution evidence or claiming that a quote is absent. False means no validated quote in these records, not that no exit route exists. '
+    'sell_out is the same saved full-balance estimate shown in the wallet UI. exit_quote is the separate Mint Club burn record; a null exit_quote does not invalidate a sell_out quote. Preserve sell_out output amount, token, quote time, output_price time, valuation and gas/execution flags. Its value_usd is a reference valuation of the received token, not verified dollar sale proceeds. reserve_reference values only the burn output; terminal_reference uses a recorded terminal route. Neither guarantees execution. Keep estimates per wallet and never sum independent quotes using shared liquidity. '
     'Only an unfiltered complete inventory needs every holdings page. For that request, follow next_offset for each approved wallet using limit 100 and state which pages remain unread if the budget prevents completion. '
     'A question about a specific token or native asset across all wallets or networks is a filtered query. token_read already returns that asset across every approved wallet, including saved native observations. Do not enumerate unrelated wallet inventory pages for a token-specific question. Inventory pages defer curve and exit details to token_read. '
     'For USD-threshold questions, pass minimum_value_usd to token_read. Use the exact returned position_count, including the combined records_read count, rather than counting rows yourself. Unpriced and outside-USD positions are reported separately, not valued at zero. '
@@ -81,7 +83,7 @@ def read_receipt(name, arguments, result, delivered=True):
         receipt['snapshot_id']=result.get('snapshot_id')
         result=result['wallets'][0]
     if isinstance(result,dict):
-        for key in ('offset','next_offset','asset_count','position_count','snapshot_id'):
+        for key in ('offset','next_offset','asset_count','position_count','snapshot_id','query_scope'):
             if key in result:receipt[key]=result[key]
         for key in ('assets','positions'):
             if isinstance(result.get(key),list):receipt['page_end']=result.get('offset',0)+len(result[key])
@@ -89,7 +91,12 @@ def read_receipt(name, arguments, result, delivered=True):
 
 def read_completion(message, receipts, tools):
     """Validate declared plans and literal requests against delivered receipts."""
-    names=set(re.findall(r'\b(?:portfolio_read|wallet_read|snapshot_read|snapshots_compare|token_read|job_read|job_list|snapshots_list)\b',message))
+    ranking=re.search(r'\btop[- ]*(\d+|one|two|three|four|five|ten)\b|상위\s*(\d+|다섯|열)',message,re.I)
+    requested_rank=None
+    if ranking:
+        raw=next(v for v in ranking.groups() if v).lower()
+        requested_rank=int(raw) if raw.isdigit() else {'one':1,'two':2,'three':3,'four':4,'five':5,'ten':10,'다섯':5,'열':10}[raw]
+    names=set(re.findall(r'\b(?:holdings_query|portfolio_read|wallet_read|snapshot_read|snapshots_compare|token_read|job_read|job_list|snapshots_list)\b',message))
     literal_names=names.copy()
     decoder=json.JSONDecoder();requested=[]
     for match in re.finditer(r'\{',message):
@@ -103,7 +110,7 @@ def read_completion(message, receipts, tools):
             for read in plan['reads']:
                 if isinstance(read,dict) and isinstance(read.get('name'),str) and isinstance(read.get('arguments'),dict):
                     names.add(read['name']);requested.append((read['name'],read['arguments']))
-    if not names or not requested and not re.search(r'\b(?:read|call|run|use|execute)\b|읽|호출|실행|수행|\+',message,re.I):return None
+    if not requested_rank and (not names or not requested and not re.search(r'\b(?:read|call|run|use|execute)\b|읽|호출|실행|수행|\+',message,re.I)):return None
     expanded=[]
     for receipt in receipts:
         expanded.extend(receipt.get('reads',[]) if receipt['name']=='records_read' else [receipt])
@@ -174,7 +181,8 @@ def read_completion(message, receipts, tools):
     exhaustive=bool(re.search(r'\b(?:complete|full)\s+inventory\b|\ball\s+(?:holdings|assets|positions)\b|전체\s*(?:보유|자산|목록)',message,re.I))
     groups={}
     for r in expanded:
-        if r['name'] not in ('wallet_read','snapshot_read','snapshots_compare','inventory_page'):continue
+        if r['name'] not in ('wallet_read','snapshot_read','snapshots_compare','inventory_page','holdings_query'):continue
+        if r['name']=='holdings_query' and (r.get('query_scope') or {}).get('mode')!='search':continue
         if not isinstance(r.get('arguments'),dict):continue
         if r['status']=='failed' and any(matches(r['name'],r.get('arguments',{}),ok) for ok in completed):continue
         if r['name']=='inventory_page' and not exhaustive:continue
@@ -194,6 +202,15 @@ def read_completion(message, receipts, tools):
             offset=page['next_offset']
         if not finished and (exhaustive or any(r.get('next_offset') is not None for r in pages)):
             unread.append({'name':name,'arguments':{**json.loads(identity),'offset':offset},'snapshot_id':snapshot})
+    if requested_rank:
+        count=requested_rank
+        ranked=[r for r in completed if r['name']=='holdings_query' and (r.get('query_scope') or {}).get('mode')=='rank']
+        if not any(q.get('full_inventory_scanned') and q.get('complete') and q.get('offset')==0 and q.get('requested_limit',0)>=count for r in ranked for q in [r['query_scope']]):
+            missing.append('holdings_query rank for the requested top '+str(count))
+    for r in completed:
+        q=r.get('query_scope')
+        if q and not q.get('complete'):missing.append('holdings_query result detail was truncated')
+    missing.extend('holdings_query has unread matching records' for r in unread if r['name']=='holdings_query')
     if exhaustive:missing.extend(r['name']+' unread offset '+str(r['arguments']['offset']) for r in unread)
     return {'status':'partial' if missing or failed else 'complete','missing':list(dict.fromkeys(missing)),'failed':failed,'unread_pages':unread,'completed_reads':sum(r['name']!='inventory_page' for r in completed)}
 
@@ -251,8 +268,7 @@ def config_input(value, root):
     else: result['wallet'] = None
     return result
 
-def projection(root, config, *, token_id=None, limit=12, offset=0, wallet_key=None, inventory=False):
-    if config['scope'] == 'none': return {'scope':'none','note':'No automatic wallet context supplied.'}
+def scoped_wallets(root,config):
     import sys
     sys.path.insert(0,str(Path(__file__).resolve().parent/'viewer'))
     from model import load_state
@@ -261,6 +277,11 @@ def projection(root, config, *, token_id=None, limit=12, offset=0, wallet_key=No
     if config['scope'] == 'wallet':
         wallets = [w for w in wallets if w['key'] == config['wallet']]
         if len(wallets) != 1: raise JobError('wallet_missing','The approved wallet is no longer registered. Review your context settings.')
+    return wallets
+
+def projection(root, config, *, token_id=None, limit=12, offset=0, wallet_key=None, inventory=False):
+    if config['scope'] == 'none': return {'scope':'none','note':'No automatic wallet context supplied.'}
+    wallets=scoped_wallets(root,config)
     wallets=[{**w,'recorded_valuation':recorded_valuation(w['assets'])} for w in wallets]
     if token_id is not None:
         wallets=[{**wallet,'assets':[a for a in wallet['assets'] if a['id']==token_id]} for wallet in wallets]
@@ -344,12 +365,13 @@ def wallet_facts(wallets, *, pool_budget=40_000):
             if item['archived']:item['historical_value_usd']=asset.get('historical_value_usd')
             item['price'] = pick(asset['price'],('usd','basis','quality','observed_at')) if asset.get('price') else None
             item['exit_quote'] = asset.get('exit_quote')
-            item['exit_quote_recorded'] = asset.get('exit_quote') is not None
+            item['sell_out'] = asset.get('sell_out')
+            item['exit_quote_recorded'] = item['exit_quote'] is not None or item['sell_out'] is not None
             item['exit_route'] = asset.get('exit_route')
             item['markets'] = asset.get('links',[])
             pools=asset.get('market_pools',[]);item['pools']=[];item['pools_recorded']=len(pools)
             for pool in pools[:12]:
-                fact={**pick(pool,('venue','pool','url','liquidity_usd','price_usd','observed_at')),
+                fact={**pick(pool,('venue','pool','url','liquidity_usd','price_usd','observed_at','version_labels','fee_bps','pool_kind')),
                       'pair':[pick(coin,('address','symbol')) for coin in pool.get('pair',[])]}
                 cost=len(json.dumps(fact,ensure_ascii=False).encode())+2
                 if cost>pool_budget:break
@@ -615,7 +637,7 @@ class AgentStore:
     def _run(self,key,config,prompt,message,epoch):
         try:
             turn=self.turns[key];cancel=turn['cancel']
-            tools=None;transcript=[];repair=None;repaired=False;completion_retried=False;planning=False;deadline=time.monotonic()+420
+            tools=None;transcript=[];blocked_context=set();repair=None;repaired=False;completion_retried=False;planning=False;deadline=time.monotonic()+420
             if not turn['test'] and config.get('wallet_tools') and config['scope']!='none':
                 from kira_research_tools import ResearchTools,CATALOG
                 @contextmanager
@@ -658,6 +680,8 @@ class AgentStore:
                     repair='No tool was executed. First return only a records_read plan with every requested source, or an empty reads list for an action-only request.';repaired=True;continue
                 repair=None
                 if step==8:raise JobError('tool_limit','The research step limit was reached. Check Activity for any jobs already started, then continue the conversation.')
+                signature=json.dumps(request,sort_keys=True,ensure_ascii=False)
+                if signature in blocked_context:raise JobError('context_limit','This request keeps returning too much detail. Ask for a token search, a ranking or an aggregate summary. Earlier completed reads are retained.')
                 try:
                     fields(request,['kira_tool','arguments'])
                     with self.lock:
@@ -666,7 +690,7 @@ class AgentStore:
                     result=tools.call(request['kira_tool'],request['arguments'],str(uuid.uuid5(uuid.UUID(key),str(step))))
                     if request['kira_tool']=='records_read':planning=False
                     executed_result=result
-                    if len(json.dumps(result,ensure_ascii=False).encode())>(280000 if request['kira_tool']=='records_read' else 160000):result={'error':'This result exceeds the context limit. Choose smaller wallet pages or a token-specific read.'}
+                    if len(json.dumps(result,ensure_ascii=False).encode())>(280000 if request['kira_tool']=='records_read' else 160000):result={'error':{'code':'context_limit','message':'This result exceeds the context limit. Use holdings_query for names, rankings or aggregates, or request a smaller page.'}}
                 except JobError as error:
                     if error.code=='cancelled':raise
                     result={'error':{'code':error.code,'message':str(error)}}
@@ -674,6 +698,7 @@ class AgentStore:
                 item={'tool':request['kira_tool'],'arguments':request['arguments'],'result':result}
                 if len(json.dumps(transcript+[item],ensure_ascii=False).encode())>280000:
                     item['result']={'error':{'code':'context_limit','message':'The accumulated research context limit was reached. Use a smaller wallet_read page or a specific token, or finish with the evidence already received.'}}
+                if isinstance(item['result'],dict) and isinstance(item['result'].get('error'),dict) and item['result']['error'].get('code') in ('context_limit','context_too_large'):blocked_context.add(signature)
                 transcript.append(item)
                 with self.lock:
                     delivered=item['result']
@@ -693,8 +718,7 @@ class AgentStore:
                     completion=read_completion(message,turn.get('tool_calls',[]),tools)
                     turn['read_completion']=completion
                     if completion and completion['status']=='partial':
-                        missing=', '.join(completion['missing']) or 'failed read requests'
-                        answer=('요청한 자료 읽기를 모두 완료하지 못했습니다: ' if re.search(r'[가-힣]',message) else 'Requested reads are incomplete: ')+missing+'.\n\n'+answer
+                        answer=('저장된 자료 중 요청에 필요한 일부 기록을 확인하지 못했습니다. 아래 답변은 확인된 범위만 포함합니다.' if re.search(r'[가-힣]',message) else 'Some requested records could not be checked. This answer covers only the available evidence.')+'\n\n'+answer
                     self.messages.extend([{'role':'user','text':message},{'role':'assistant','text':answer}]);self.messages=self.messages[-24:]
                     self.updated_at=datetime.now(timezone.utc).isoformat();self._remember()
                 turn.update(state='partial' if (turn.get('read_completion') or {}).get('status')=='partial' else 'succeeded',answer=answer)

package/kira_jobs.py

@@ -191,8 +191,27 @@ class JobStore:
                 final=published_asset_progress(path,(stat.st_mtime_ns,stat.st_size,stat.st_ino))
                 if final and final[0]==wallet.lower():job['asset_progress']={chain:dict(row) for chain,row in final[1]}
             except (OSError,ValueError,TypeError,AttributeError):pass
+        if job['state']=='failed' and any(e.get('code')=='engine_failed' for e in job['errors']):
+            failure=self.engine_failure(job)
+            job['errors']=[{'code':failure.code,'message':str(failure)}]
         return job
 
+    def engine_failure(self, job):
+        """Expose only recognized failure categories, never engine diagnostics.
+
+        Older checkpoints predate error codes. Project their exact known error
+        without rewriting the historical job or leaking provider responses.
+        """
+        try:
+            run=read(self.root/job['checkpoint']/'run.json')
+            wallet=job['input'].get('wallet') or job['input'].get('address')
+            if run.get('status')=='failed' and run.get('wallet_address','').lower()==wallet.lower():
+                if (run.get('error_code')=='network_scope_changed' or
+                        run.get('error')=='Mint Club SDK network/deployment scope changed. Reconcile networks.json before analysis.'):
+                    return JobError('network_scope_changed',"Kira's network configuration did not pass its compatibility check. Update Kira, then retry.")
+        except (OSError,ValueError,TypeError,AttributeError):pass
+        return JobError('engine_failed','The lookup stopped unexpectedly. Retry to continue from any saved checks.')
+
     def list(self):
         with self.locked():
             return sorted((self.get(p.stem) for p in self.jobs.glob('*.json')), key=lambda j: j['created_at'], reverse=True)
@@ -702,7 +721,7 @@ class JobStore:
             if yielded:raise JobError('yielded','Detailed research yielded to a short operation. Saved checkpoints are retained and detailed research resumes automatically.')
             if self.get(job['job_id'])['stage']=='market_paused':raise JobError('market_budget','Balances are saved. Market verification reached its time budget. Resume this job in Activity to continue saved checks. Pending pools are not verified absent.')
             if self.get(job['job_id'])['stage']=='research_paused':raise JobError('research_pending','Research has saved unfinished ranges ready for continuation.')
-            raise JobError('engine_failed', 'Analysis stopped before publication. Check connection settings and resume saved evidence.')
+            raise self.engine_failure(job)
         finally:
             stop_child(); selector.close(); child.stdout.close()