kira-wallet 0.1.14 → 0.1.16

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
@@ -82,15 +82,46 @@ on-chain checkpoint status. Deferred candidates and pending networks are not
 failed reads or zero holdings. Historical observations cannot establish current
 execution, transfers or realized profit.
 
-`records_read` executes one bounded plan of up to eight declared read tools.
-Each child has its own host receipt. Literal JSON read requests are matched
-against their actual arguments, including chain and contract. Full inventory
+Before answering, scoped research chat must declare a `records_read` plan
+containing every requested source, up to 32 declared read tools. An empty plan
+is for greetings or action-only requests. Planning cannot start a refresh.
+Each child has its own host receipt. The declared plan and literal JSON read
+requests are matched against actual arguments, including chain and contract.
+An incomplete delivered plan receives one bounded continuation attempt before
+the turn is marked partial. Full inventory
 requests require contiguous delivered pages through `next_offset: null`.
 Failed or undelivered pages remain unread, with retry arguments in the turn's
 `read_completion`. Automatic context is not a requested tool receipt. This
 bounded check does not verify every semantic requirement in natural prose.
 
+Token-specific queries read all approved wallets with `token_read`, without
+enumerating unrelated inventory pages. Its optional `minimum_value_usd` filters
+recorded mainnet values. Unknown and outside-USD positions have separate counts.
+`position_count` is computed by the host; a read-plan count deduplicates returned
+wallet/chain/asset identities rather than asking the model to tally its table.
+
 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
@@ -246,6 +254,10 @@ The optional asset_progress map persists total, checked, quoted and unknown
 counts per mainnet chain. checked equals quoted plus unknown, not successful
 valuation. It survives process restarts, pause and resume and current-step count
 resets. The total can grow with discovered holdings.
+For a published sell analysis, job reads project these counters from the final
+per-token cash-out classifications. Testnet/outside-USD records are excluded.
+This also corrects older completed summaries without rewriting their original
+progress events or snapshots. Running and paused jobs retain checkpoint counts.
 Each slice registers the known inventory for all mainnet chains before market
 checks, so the first completed chain does not imply all discovered work is done.
 The viewer separately shows saved asset checks, available prices and unresolved checks. It does not derive

package/docs/ONBOARDING_CHAT_CONTRACT.md

@@ -37,7 +37,7 @@ Kira uses fixed executable argv, stdin for prompts, a private empty working dire
 
 Native CLI and administrator policy are a separate trust boundary. These settings are invocation controls, not an OS container. Claude managed policy can still apply. Setup requires explicit acknowledgement of the native CLI trust boundary. Kira-local retention controls Kira's conversation files only; vendor and managed CLI data policies are separate. History-off conversations stay in memory and the browser draft is not persisted. Previous saved conversations are preserved but never automatically attached to a new scope.
 
-Chat cannot sign, trade, run arbitrary commands or change provider settings. With the separate wallet research capability enabled, a bounded host loop validates typed tool requests from the native response. It reads allowlisted current and historical facts inside the approved wallet scope and admits holdings or price jobs through the existing durable API. Legacy settings default this new capability off. New setup recommends portfolio context and research tools. No-context chat receives no wallet tools. Epoch, cancellation and configuration are rechecked under the store lock before job admission. Duplicate refreshes within a turn reuse their job. Queued or running work is never a completed publication. Research already admitted persists in Activity after chat cancellation. The tool loop is limited to eight calls, 150 KB of accumulated tool results, a 400 KB prompt and 420 seconds total. Native shell, arbitrary files, browser and MCP tools remain disabled. Responses and token metadata are untrusted text. Assistant responses use a bounded Markdown subset with escaped HTML, no active links or images, and scrollable tables. Token metadata and user messages remain escaped text.
+Chat cannot sign, trade, run arbitrary commands or change provider settings. With the separate wallet research capability enabled, a bounded host loop validates typed tool requests from the native response. It reads allowlisted current and historical facts inside the approved wallet scope and admits holdings or price jobs through the existing durable API. Legacy settings default this new capability off. New setup recommends portfolio context and research tools. No-context chat receives no wallet tools. Epoch, cancellation and configuration are rechecked under the store lock before job admission. Duplicate refreshes within a turn reuse their job. Queued or running work is never a completed publication. Research already admitted persists in Activity after chat cancellation. The first response declares a read-only plan of up to 32 sources, or an empty plan for a greeting or action-only request. Every declared read is checked against delivery receipts; an incomplete plan gets one bounded continuation and remains partial if unresolved. The tool loop is limited to eight calls, 280 KB of accumulated tool results, a 400 KB prompt and 420 seconds total. Native shell, arbitrary files, browser and MCP tools remain disabled. Responses and token metadata are untrusted text. Assistant responses use a bounded Markdown subset with escaped HTML, no active links or images, and scrollable tables. Token metadata and user messages remain escaped text.
 
 All agent and chat endpoints require the existing same-origin local session, with bounded requests. Conversation jobs are separate from research jobs. Idempotent requests prevent duplicate sends. Cancellation, reset and configuration changes invalidate late responses. Tests cover disclosure projections, scope history isolation, retention, cancellation races, bounded output, unsupported CLIs, failures, duplicate sends and origin/session protection.
 

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.13
+Keep published GitHub tags, release assets and npm versions through 0.1.15
 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.14.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-0.1.16.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.14.tgz --access public
+npm publish ./dist/kira-wallet-0.1.16.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.
@@ -353,7 +353,7 @@ The operator published 0.1.13 on October 17, 2026. Its registry archive matched
 the frozen manifest and all 90 installed package members. The published archive
 remains immutable.
 
-## Release candidate: 0.1.14
+## Published 0.1.14
 
 Version 0.1.14 includes merged PR33. Private Alchemy RPC requests use a shared
 250 ms lane across hosts, with cooldown after HTTP or JSON-RPC rate limits.
@@ -392,3 +392,100 @@ Prepare and freeze the final archive from the landed version PR, then dry-run
 that exact archive. npm publication remains operator-only. Keep the personal
 0.1.13 installation, published archives and paused automation unchanged. This
 preparation does not publish a GitHub release or deploy the website.
+
+The operator published 0.1.14 on October 18, 2026. Its registry archive matched
+the frozen manifest, including SHA-256
+`c9802e76f05ae7e560fd29051beea3855e7006e99670f131de2a6322f4b1e8b8`
+and all 90 installed members. Actual acceptance checked important explorer
+balances, prices, artwork and sell-only pause/resume. A subsequent pass completed
+the sell analysis naturally and exposed the two issues addressed below.
+
+## Release candidate: 0.1.15
+
+Scoped AI research declares its complete read plan before answering. A plan
+can contain up to 32 read-only requests, so a nine-chain question is not cut
+off by the former eight-read batch bound. Host receipts cover declared plans
+in natural-language conversations as well as literal tool requests. Missing
+reads receive one bounded continuation attempt and unresolved requests stay
+partial. An empty plan supports greetings and action-only requests. Planning
+cannot enqueue research; scope, cancellation, context and time limits remain.
+Token-specific reads cover all approved wallets without unrelated inventory
+pagination. Optional USD thresholds and distinct matched-position counts are
+computed from saved values by the host; unknown and testnet values stay separate.
+This checks the declared plan, not every possible semantic interpretation of
+a question. Unknown values and recorded valuation timestamps remain explicit.
+
+Completed sell summaries use final saved per-token classifications rather than
+intermediate progress counters. Older completed jobs also show corrected totals
+without rewriting snapshots or original events. Paused/running progress remains
+resumable, and testnet values stay outside USD classifications. This changes
+neither balances nor quote execution, gas or best-route guarantees.
+
+Required gates are the full repository suite, clean installation, actual native
+AI nine-source and research-action checks, completed-summary browser checks,
+tracked/history privacy scans and an exact final archive installation. Preserve
+raw strict history findings and assess only the authorized normal CLI merge
+metadata under the ruling above. Review not selected.
+
+Prepare and freeze the final archive only from the landed release source, then
+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.
+
+## Release candidate: 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.
+Preserve the superseded unpublished archive before creating the final 0.1.16
+candidate. Only the archive matching the final manifest is a publication target.

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