kira-wallet 0.1.6 → 0.1.7

package/README.md

@@ -43,12 +43,11 @@ For a viewer without wallet or research actions, use `kira start --read-only`.
 Prefer an archive? [GitHub releases](https://github.com/realproject7/kira-wallet/releases/tag/v0.1.2)
 include the same package and its checksum.
 
-1. **Set up discovery.** In **Workspace settings**, connect an indexer for broad
-   ERC20 discovery. Public RPC alone has limited discovery; incomplete coverage
+1. **Review optional coverage.** Free research is enabled by default. In **Workspace settings**, connect Alchemy for broader
+   ERC20 discovery. Free token sources have limited coverage; incomplete coverage
    stays visible. An AI or browser wallet connection does not enable an indexer.
 2. **Add a watching wallet.** Paste a public address and give it a name. Add more
-   wallets whenever you need them. Without discovery, the form explicitly
-   offers limited research of native and Mint Club assets.
+   wallets whenever you need them. The form starts free research of native, common tokens and Mint Club assets, with keyless discovery on supported networks. First balances appear before detailed research finishes.
 3. **Connect your AI.** Install and sign in to the
    [Codex CLI](https://developers.openai.com/codex/cli) or
    [Claude Code](https://code.claude.com/docs/en/quickstart), then choose your

package/THIRD_PARTY_NOTICES.md

@@ -28,3 +28,9 @@ identifies the OWS wallet-creation integration without implying endorsement.
 Its retrieval date and source digest are in `site/assets/ows-artwork-source.json`.
 
 CASHCAT, BLAST and USDB artwork in the public reconstructed demo comes from lpTOKEN.fun token metadata, DEX Screener and CoinGecko. Token marks belong to their respective owners and identify the assets without implying affiliation or endorsement. The source URLs and chain-specific contract identities are recorded in `site/assets/token-artwork-sources.json`.
+
+The factual token inventory in `sources/known-tokens.json` includes selected
+chain/contract identities from Uniswap default-token-list at commit
+583cb696cc15778536fe0ddd416de5bd81be2023. The upstream references retain
+GPL-3.0 terms in `sources/TOKEN_LIST_LICENSE.txt`. Per-contract provenance is
+recorded in the catalog. No upstream executable code or artwork is included.

package/docs/AGENT_TOOLS.md

@@ -60,3 +60,16 @@ through the user's CLI; local storage does not imply an offline model.
 
 See [the conversation contract](ONBOARDING_CHAT_CONTRACT.md).
 The standalone stdio MCP adapter above remains read-only and separate.
+
+Native responses select the final Codex agent message. Older verified event
+streams without a phase use their last agent message. Commentary cannot become
+a tool request by concatenation. A mixed or malformed request gets one bounded
+correction; no tool executes from it and repeated malformed protocol fails
+without adding raw JSON to conversation history. Turn receipts expose only
+bounded tool names and completed/failed outcomes.
+
+Job reads include analysis phase, parent/continuation IDs and real progress
+events. Normalized chain discovery completeness is separate from a job's
+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.

package/docs/CLI.md

@@ -10,7 +10,7 @@ npm install -g kira-wallet
 kira setup
 ```
 
-The operator published npm version 0.1.5. Version 0.1.6 is a preparation candidate. GitHub v0.1.3 remains
+The operator published npm version 0.1.6. Version 0.1.7 is a preparation candidate. GitHub v0.1.3 remains
 a draft; the previous archive and checksum are available from the
 [0.1.2 GitHub release](https://github.com/realproject7/kira-wallet/releases/tag/v0.1.2).
 Registry publication remains an operator action. The code and original character assets use the MIT license.
@@ -46,7 +46,7 @@ Published 0.1.4 explains limited discovery before wallet registration and beside
 holdings. Missing coverage keeps the portfolio estimate partial. Existing snapshots require a holdings refresh after connecting
 an indexer; a price refresh does not discover missing tokens.
 
-Public RPC checks known assets and Mint Club. For broader ERC20 discovery,
+Free research checks known assets, Mint Club and keyless token candidates on supported networks. Alchemy is optional. For broader ERC20 discovery,
 open Custom RPC & token coverage, select Alchemy and follow its local key guide.
 Published 0.1.5 uses one save for Alchemy RPC and discovery; chain overrides
 remain under Advanced. Never paste the key into the browser. `kira doctor`

package/docs/FREE_RPC.md

@@ -52,15 +52,42 @@ Registry identity caching remains separate from balances.
 
 Native balances and the selected issuer/deployment-backed contracts in
 `sources/known-tokens.json` are checked before cold Mint Club enumeration.
-The small list includes USDC on seven supported mainnets, USDT on Ethereum and
-Avalanche, and WETH on Arbitrum. Decimals and quantities come from on-chain
-reads. This list does not cover all common tokens or all wrapped/bridged variants.
-
-The full Mint Club registry is still scanned. Public RPC cannot enumerate all
-arbitrary ERC20 contracts held by an address. Discovery remains incomplete
-without a working indexer on that network. Incomplete holdings show a persistent
-notice on Home and the wallet page, with a path to
-[Alchemy setup](ALCHEMY_SETUP.md) and an explicit holdings refresh.
+The catalog has 57 chain/contract identities on eight mainnets. Issuer references
+and selected Uniswap token-list records retain per-contract provenance. The
+upstream list commit and its license are bundled; no untrusted runtime list is
+loaded. Decimals and quantities come from on-chain reads. This remains a bounded
+inventory, not a claim to discover every wrapped or arbitrary token.
+
+Default research also uses Routescan without a key on individually verified
+Ethereum, Avalanche and Blast routes. Its documented free access is limited to
+two requests per second and 10,000 calls per day. Kira starts at most one call
+per second, reads at most 20 pages of 100 candidates per chain and spends at most
+25 seconds per enumeration. An isolated HTTP reader enforces a total deadline,
+including DNS and response bodies. Unsafe pagination, outages, malformed data
+and limits keep coverage partial. Provider quantities and prices never replace
+RPC-verified balances. Other Routescan chains are not presumed supported.
+Explicit keyless opt-outs and custom-only preferences remain respected.
+
+Initial reports check Base, Ethereum and Blast, up to 128 candidates per chain.
+Selected common contracts take priority. Remaining candidates and networks are
+explicitly pending. A durable background continuation scans every configured
+network, the full Mint Club registry and markets. Registry identity prefixes
+are saved incrementally; balances are never shared between wallets. Batches
+contain at most 128 reads, with splitting only for verified payload limits.
+New initial work takes priority over detailed research. Older same-wallet
+continuations cannot replace newer evidence.
+
+Public RPC cannot enumerate all arbitrary ERC20 contracts. Alchemy is an
+optional broader candidate source and backup RPC. Discovery calls made through
+the wallet engine have a 25-second initial or 60-second detailed per-chain
+budget. Native balances, free candidates and Mint Club research remain usable
+without it. Missing or deferred evidence stays unknown. Persistent coverage
+notices distinguish pending work from failed reads and offer retry or optional
+[Alchemy setup](ALCHEMY_SETUP.md).
+
+Keyless sources: [Routescan addresses](https://routescan.io/docs/api/addresses),
+[API access](https://routescan.io/docs/plans-and-limits/api-keys-and-pricing),
+[rate limits](https://routescan.io/docs/plans-and-limits/rate-limits).
 
 ## Read preferences
 

package/docs/JOB_CONTRACT.md

@@ -121,3 +121,27 @@ its projection receipt without another provider request.
 
 The read-only stdio MCP adapter uses the same job and snapshot service. It has
 no mutation tools and requires separate operator-approved client setup.
+
+## Initial evidence and continuations in 0.1.7
+
+A valid wallet admission records its identity under a short registry lock.
+Idempotent replay repairs missing admission without undoing later name edits.
+New analysis jobs have `analysis_phase: baseline`. The first usable chain
+publishes an immutable `initial/` snapshot; the running job can reference it
+without claiming that the job is finished. The baseline publishes its own final
+partial snapshot and admits exactly one durable `enrichment` continuation with
+`parent_job_id`. The parent records `continuation_id`.
+
+Baseline work runs before enrichment. New baseline admission can preempt a
+running continuation. Saved chain evidence and verified registry identity
+prefixes survive; an interrupted registry batch is read again. A newer request
+for the same wallet supersedes older detailed work. Generation checks prevent
+an older result from replacing the latest pointer, while preserving historical
+evidence. Explicit cancellation of baseline prevents automatic continuation.
+
+`onchain_progress` events identify the actual operation, chain, checked count
+and known total. `chain.status: complete` concerns the on-chain checkpoint.
+Normalized wallet `complete` concerns general token discovery. Registry coverage,
+candidate failures, deferred candidates and pending RPC reads are separate facts.
+These flags do not prove exhaustive holdings. First results can be read while
+background work remains active.

package/docs/RELEASE.md

@@ -49,15 +49,14 @@ Claude model choices, exposes model and permission changes in Workspace settings
 and provides one Alchemy connection save. Its registry version was confirmed on
 2026-10-09. Published package bytes remain immutable.
 
-The next candidate is **0.1.6**. It adds a paced local RPC pool, core-chain public
+Published **0.1.6** adds a paced local RPC pool, core-chain public
 alternatives, public-first custom backup, fixed-block hash checks and a small
 known-token catalog. Home and wallet pages display incomplete coverage with an
 Alchemy setup action. The settings guide explains account setup, private local
 key import and an explicit holdings refresh. Missing or malformed discovery data
 cannot become a completed empty inventory.
 
-Version 0.1.6 requires review and operator registry publication. It is not yet
-published. The showcase remains a separate deployment. See
+Version 0.1.6 is published and immutable. The showcase remains a separate deployment. See
 [free RPC behavior](FREE_RPC.md) and [Alchemy setup](ALCHEMY_SETUP.md).
 
 The operator published npm **0.1.2** on 2026-10-05. Its registry archive was
@@ -80,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 GitHub v0.1.1, its tag and its released archive immutable. Versions 0.1.2, 0.1.3, 0.1.4 and 0.1.5 are also published and immutable. Do not rebuild them from later documentation
+Keep GitHub v0.1.1, its tag and its released archive immutable. Versions 0.1.2, 0.1.3, 0.1.4, 0.1.5 and 0.1.6 are also published and immutable. Do not rebuild them from later documentation
 commits. Future package changes need a new version. Release preparation does not
 publish a GitHub release, merge PR 19, promote the website or publish to npm.
 Registry publication remains operator-only. The coding agent never publishes.
@@ -95,18 +94,38 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.1.6.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-0.1.7.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.6.tgz --access public
+npm publish ./dist/kira-wallet-0.1.7.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.
 After publication, verify the registry archive and perform a fresh install
 before marking the new onboarding flow as available to npm users.
 
+## Proposed 0.1.7 behavior
+
+The candidate enables useful keyless research by default, expands the curated
+contract inventory and separates first recorded balances from exhaustive
+background research. Pending candidates, registry work and other networks stay
+visible. Current wallet evidence cannot roll back when an older continuation
+resumes. See [coverage and limits](FREE_RPC.md).
+
+Codex uses the final native message rather than joined commentary. Mixed tool
+protocol receives one bounded correction and is never rendered as a completed
+answer. Claude retains its restricted native adapter. Tool receipts contain
+names and outcomes, without raw arguments. Job checkpoints and normalized token
+discovery flags have separate meanings. Imported connection references reconcile
+with untouched settings fields while preserving edited drafts.
+
+The next archive is **0.1.7**, unpublished until the operator runs the command.
+Release readiness requires the repository suite, clean installation, source and
+history privacy scans, independent review and the frozen archive manifest.
+No live-extension or human passphrase acceptance is inferred from these checks.
+
 ## Verified 0.1.0 publication
 
 The operator published 0.1.0, verified on 2026-10-04. The registry archive has

package/kira_agent.py

@@ -42,7 +42,7 @@ SYSTEM = ('You are Kira, a careful wallet research partner. Answer in the langua
     'and full-balance output only when a validated quote exists. DEX pool TVL is not a sell quote. '
     'Missing execution quotes mean sale proceeds, fees, gas and price impact are unknown. '
     'For network questions, group by wallet and distinguish known assets from missing coverage. '
-    'A chain complete flag means general ERC20 discovery was checked; it does not prove native RPC reads succeeded. An indexer check and unavailable RPC are separate coverage facts, not conflicting records. '
+    'In normalized wallet facts, chain complete means general ERC20 discovery was checked. In job chains, status complete means an on-chain checkpoint finished. These are different stages. Neither flag alone proves all holdings are known. registry_complete and candidate_balance_errors describe separate read coverage. An indexer check and unavailable RPC are separate coverage facts, not conflicting records. '
     'An explicit chains.native_balance of zero is an observed native balance at its recorded time and block; null is unknown. Empty positive-holding inventories do not erase these observations. '
     'For saved-analysis comparisons, use snapshots_compare and read both snapshots. coverage_changed compares full evidence, including times and blocks, not just network status flags. price_references_changed may include changed reference values or times, not balances. '
     'Snapshot reads are normalized evidence. Compare chain observations and snapshot_price_references; never claim these are the only raw fields that changed. '
@@ -140,7 +140,7 @@ def wallet_facts(wallets, *, pool_budget=40_000):
     for wallet in wallets:
         row = pick(wallet,('address','tags','name','analysed_at','prices_at','balance_observed_at','known_value_usd','unpriced_count','status'))
         if not wallet.get('analysed_at'): row['known_value_usd']=None
-        row['chains'] = [pick(c,('id','name','environment','complete','rpc_available','native_symbol','native_balance','native_observed_at','native_block_number','registry_block_number')) for c in wallet['chains']]
+        row['chains'] = [pick(c,('id','name','environment','complete','rpc_available','native_symbol','native_balance','native_observed_at','native_block_number','registry_block_number','discovery_status','registry_complete','registry_phase','rpc_pending','candidate_balance_errors','candidate_deferred')) for c in wallet['chains']]
         row['snapshot_price_references'] = wallet.get('snapshot_price_references',{})
         row['assets'] = []
         for asset in wallet['assets']:
@@ -211,11 +211,14 @@ def run_native(config, prompt, cancel, *, timeout=180):
             else:
                 events = [json.loads(line) for line in output.splitlines() if line.strip()]
                 if not any(e.get('type') == 'turn.completed' for e in events): raise ValueError()
-                answer = '\n\n'.join(e['item'].get('text','') for e in events if e.get('type') == 'item.completed' and e.get('item',{}).get('type') == 'agent_message')
+                messages = [e['item'] for e in events if e.get('type') == 'item.completed' and e.get('item',{}).get('type') == 'agent_message']
+                finals = [m for m in messages if m.get('phase')=='final_answer']
+                # Older verified CLIs omit phase. Only their last message is final.
+                answer = (finals or [m for m in messages if not m.get('phase')])[-1].get('text','') if finals or any(not m.get('phase') for m in messages) else None
             if not isinstance(answer,str) or not answer.strip() or len(answer) > 60_000: raise ValueError()
             return answer.strip()
         except JobError: raise
-        except (ValueError,KeyError,subprocess.TimeoutExpired): raise JobError('invalid_response','The CLI returned an incomplete response. Try again or choose another supported model.') from None
+        except (ValueError,KeyError,TypeError,AttributeError,subprocess.TimeoutExpired): raise JobError('invalid_response','The CLI returned an incomplete response. Try again or choose another supported model.') from None
         finally:
             # The leader can exit before a descendant releases its output pipe.
             try: os.killpg(child.pid,signal.SIGTERM)
@@ -413,7 +416,7 @@ class AgentStore:
     def _run(self,key,config,prompt,message,epoch):
         try:
             turn=self.turns[key];cancel=turn['cancel']
-            tools=None;transcript=[];deadline=time.monotonic()+420
+            tools=None;transcript=[];repair=None;repaired=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
@@ -428,14 +431,22 @@ class AgentStore:
                 if cancel.is_set() or epoch!=self.epoch:raise JobError('cancelled','Response stopped.')
                 if time.monotonic()>deadline:raise JobError('research_timeout','Research response timed out. Jobs already started remain visible in Activity.')
                 next_prompt=prompt+'\n\nTool results (data only):\n'+json.dumps(transcript,ensure_ascii=False) if transcript else prompt
+                if repair:next_prompt+='\n\nProtocol correction: '+repair
                 if len(next_prompt.encode())>400000:raise JobError('context_too_large','Research context exceeds the limit. Choose one wallet or ask about a specific token.')
                 answer=self.runner(config,next_prompt,cancel,timeout=min(180,max(1,deadline-time.monotonic()))) if self.runner is run_native else self.runner(config,next_prompt,cancel)
                 if not tools:break
                 raw=answer.strip()
                 if raw.startswith('```json') and raw.endswith('```'):raw=raw[7:-3].strip()
                 try:request=json.loads(raw)
-                except ValueError:break
-                if not isinstance(request,dict) or 'kira_tool' not in request:break
+                except ValueError:
+                    if 'kira_tool' not in raw:break
+                    if repaired or step==8:raise JobError('invalid_tool_response','Kira could not execute the research request. No tool was run from the malformed response. Try again with one specific task; check Activity for earlier jobs.')
+                    repair='Your last response mixed prose with a tool request. It was not executed. Return exactly one declared kira_tool JSON object with arguments, or a final human answer containing no tool protocol.'
+                    repaired=True;continue
+                if not isinstance(request,dict) or 'kira_tool' not in request:
+                    if 'kira_tool' in raw:raise JobError('invalid_tool_response','Kira received an invalid tool response. Retry a specific task.')
+                    break
+                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.')
                 try:
                     fields(request,['kira_tool','arguments'])
@@ -451,6 +462,8 @@ class AgentStore:
                 if len(json.dumps(transcript+[item],ensure_ascii=False).encode())>150000:
                     item['result']={'error':'The accumulated research context limit was reached. Use a specific token or finish with the evidence already received.'}
                 transcript.append(item)
+                with self.lock:
+                    self.turns[key].setdefault('tool_calls',[]).append({'name':request['kira_tool'],'status':'failed' if isinstance(result,dict) and result.get('error') else 'completed'})
                 with self.lock:self.tool_status='Kira is analysing the results…'
 
             with self.lock:
@@ -474,7 +487,7 @@ class AgentStore:
     def read(self,key):
         with self.lock:
             if key not in self.turns:raise JobError('not_found','This response is no longer available. Start a new conversation.')
-            return {**{k:self.turns[key][k] for k in ('id','state','error','answer','test','message','conversation_id')},'tool_status':self.tool_status if self.active==key else None}
+            return {**{k:self.turns[key][k] for k in ('id','state','error','answer','test','message','conversation_id')},'tool_calls':self.turns[key].get('tool_calls',[]),'tool_status':self.tool_status if self.active==key else None}
 
     def cancel(self,key):
         with self.lock:

package/kira_cli.py

@@ -235,7 +235,7 @@ def main():
                 from kira_config import provider_config
                 cfg=provider_config(cfg,'alchemy',args.key_env)
                 cfg['secret_env_file']=str(file);cfg['discovery']['explorers']=True
-            elif args.command=='discovery':cfg['discovery']={'provider':args.provider,'key_env':args.key_env,'explorers':args.explorers}
+            elif args.command=='discovery':cfg['discovery']={**cfg['discovery'],'provider':args.provider,'key_env':args.key_env,'explorers':args.explorers}
             elif args.setting=='public':cfg['rpc']['mode']='public'
             else:
                 cfg['rpc'].update(mode='custom')

package/kira_config.py

@@ -17,7 +17,7 @@ def config_path():
 
 def default_config():
     return {'schema_version':1,'rpc':{'mode':'public','allow_public_fallback':True,'priority':'public_first','chains':{}},
-            'discovery':{'provider':'none','key_env':'ALCHEMY_API_KEY','explorers':False}}
+            'discovery':{'provider':'none','key_env':'ALCHEMY_API_KEY','explorers':False,'public':True}}
 
 def provider_config(config, provider, key_env):
     """One settings transition. Preserve explicit fallback and custom overrides."""
@@ -45,7 +45,8 @@ def load_config():
     if not isinstance(discovery,dict) or discovery.get('provider') not in ('none','alchemy') or type(discovery.get('explorers',False)) is not bool:
         raise ValueError('Invalid discovery configuration.')
     if rpc.get('priority','public_first') not in ('public_first','custom_first'):raise ValueError('Invalid RPC priority.')
-    if set(rpc)-{'mode','allow_public_fallback','priority','chains'} or set(discovery)-{'provider','key_env','explorers'}:raise ValueError('Unknown provider configuration fields.')
+    if type(discovery.get('public',True)) is not bool:raise ValueError('Invalid public discovery preference.')
+    if set(rpc)-{'mode','allow_public_fallback','priority','chains'} or set(discovery)-{'provider','key_env','explorers','public'}:raise ValueError('Unknown provider configuration fields.')
     if any(not isinstance(row,dict) or set(row)-{'url_env','alchemy_network'} for row in rpc['chains'].values()):raise ValueError('Unknown RPC endpoint fields.')
     for name in [discovery.get('key_env'),*[row.get('url_env') if isinstance(row,dict) else None for row in rpc['chains'].values()]]:
         if not isinstance(name,str) or not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]*',name):raise ValueError('Credentials must use valid environment references.')

package/kira_jobs.py

@@ -123,13 +123,16 @@ class JobStore:
         job = read(path)
         if not isinstance(job,dict) or type(job.get('schema_version')) is not int or job.get('schema_version') != 1: raise JobError('unsupported_version', 'Unsupported persisted job version.')
         required={'schema_version','job_id','operation','input','state','attempt','sequence','result','previous_result','key_hash','request_hash','created_at','updated_at','cancel_requested','checkpoint','stage','events','errors','chains'}
-        optional={'raw_hash','control_receipts','control_raw','provider_configuration','started_at'}
+        optional={'raw_hash','control_receipts','control_raw','provider_configuration','started_at','analysis_phase','parent_job_id','continuation_id'}
         if required-set(job) or set(job)-required-optional or job['job_id']!=job_id or job['checkpoint']!='snapshots/jobs/'+job_id or not isinstance(job['operation'],str) or job['operation'] not in {'wallet.add','wallet.refresh','prices.refresh','wallet.setTags','settings.rpc','settings.discovery','settings.provider'} or not isinstance(job['state'],str) or job['state'] not in TERMINAL|{'queued','running'} or any(type(job[k]) is not int or job[k]<0 for k in ('attempt','sequence')) or type(job['cancel_requested']) is not bool or not isinstance(job['input'],dict) or any(not isinstance(job[k],list) for k in ('events','errors')) or not isinstance(job['chains'],dict):
             raise JobError('invalid_envelope','Persisted job validation failed. Preserve the file for recovery.')
         names={'wallet.add':['address','tag'],'wallet.refresh':['wallet'],'prices.refresh':['wallet'],'wallet.setTags':['wallet','tags'],
             'settings.rpc':['mode','chains','allow_public_fallback'],'settings.discovery':['provider','key_env'],'settings.provider':['provider','key_env']}[job['operation']]
         if job['operation']=='settings.rpc' and 'priority' in job['input']:names=names+['priority']
         fields(job['input'],names)
+        if 'analysis_phase' in job and job['analysis_phase'] not in ('baseline','enrichment'):raise JobError('invalid_envelope','Invalid analysis phase.')
+        for field in ('parent_job_id','continuation_id'):
+            if field in job:identifier(job[field])
         wallet=job['input'].get('wallet') or job['input'].get('address')
         if wallet is not None and (not isinstance(wallet,str) or not ADDRESS.fullmatch(wallet)):raise JobError('invalid_envelope','Persisted wallet identity is invalid.')
         return job
@@ -206,7 +209,27 @@ class JobStore:
             return value.copy()
         raise JobError('unsupported_operation', 'Unsupported job operation.')
 
-    def submit(self, request):
+    def admit_wallet(self, job):
+        if job['operation'] not in ('wallet.add','wallet.refresh'):return job
+        from wallet import register, registry_locked
+        with registry_locked(self.root):
+            registry=read(self.root/'wallets.json')
+            admissions=registry.setdefault('wallet_admissions',{})
+            address=job['input'].get('address') or job['input'].get('wallet')
+            entry=next((w for w in registry['wallets'] if w['address_key']==address.lower()),None)
+            if job['job_id'] not in admissions:
+                legacy_done=not job.get('analysis_phase') and (job['state']!='queued' or job['attempt']>0) and entry is not None
+                if job['operation']=='wallet.add' and not legacy_done:
+                    entry=register(registry,address,job['input']['tag'])
+                if job.get('analysis_phase')=='baseline':entry['research_generation']=job['job_id']
+                admissions[job['job_id']]=address.lower()
+                atomic(self.root/'wallets.json',registry)
+            elif entry is None and job['operation']=='wallet.add':
+                register(registry,address,job['input']['tag'])
+                atomic(self.root/'wallets.json',registry)
+        return job
+
+    def submit(self, request, *, phase='baseline', parent=None):
         fields(request, ['schema_version', 'operation', 'input', 'idempotency_key'])
         if type(request['schema_version']) is not int or request['schema_version'] != 1:
             raise JobError('unsupported_version', 'Expected request schema version 1.')
@@ -218,19 +241,19 @@ class JobStore:
             if not isinstance(operation,str):raise JobError('unsupported_operation','Expected a typed operation name.')
             key_hash = digest(key); receipt = self.jobs / 'requests' / (key_hash + '.json')
             raw_hash=digest({'operation':operation,'input':request['input']})
-            if receipt.exists() and read(receipt).get('raw_hash')==raw_hash:return self.get(read(receipt)['job_id'])
+            if receipt.exists() and read(receipt).get('raw_hash')==raw_hash:return self.admit_wallet(self.get(read(receipt)['job_id']))
             for p in self.jobs.glob('*.json'):
                 saved=self.get(p.stem)
                 if saved.get('control_raw',{}).get(key_hash)==raw_hash or saved['key_hash']==key_hash and saved.get('raw_hash')==raw_hash:
                     fingerprint=saved.get('control_receipts',{}).get(key_hash,saved['request_hash'])
                     atomic(receipt,{'schema_version':1,'request_hash':fingerprint,'raw_hash':raw_hash,'job_id':saved['job_id']})
-                    return saved
+                    return self.admit_wallet(saved)
             value = self.normalize(operation, request['input'])
             fingerprint = digest({'operation': operation, 'input': value})
             if receipt.exists():
                 old = read(receipt)
                 if old['request_hash'] != fingerprint: raise JobError('idempotency_conflict', 'This request key already belongs to another operation.')
-                return self.get(old['job_id'])
+                return self.admit_wallet(self.get(old['job_id']))
             # Recover an envelope committed before its request receipt.
             existing = next((j for p in self.jobs.glob('*.json') if (j := self.get(p.stem))['key_hash'] == key_hash or key_hash in j.get('control_receipts',{})), None)
             if existing:
@@ -261,7 +284,10 @@ class JobStore:
                     'created_at': now(), 'updated_at': now(), 'sequence': 0, 'cancel_requested': False,
                     'stage': 'queued', 'events': [], 'checkpoint': 'snapshots/jobs/' + job_id,
                     'result': None, 'previous_result': previous, 'errors': [],'chains':{}}
+                if operation in ('wallet.add','wallet.refresh'):job['analysis_phase']=phase
+                if parent:job['parent_job_id']=parent
                 self.save(job)
+            self.admit_wallet(job)
             atomic(receipt, {'schema_version': 1, 'request_hash': fingerprint,'raw_hash':raw_hash, 'job_id': job['job_id']})
             return job
 
@@ -361,11 +387,11 @@ class JobStore:
                 self.save(job)
 
     def event(self, job_id, event):
-        allowed = {'registered', 'discovery', 'chain', 'dex_discovery', 'token_images', 'published', 'failed'}
+        allowed = {'registered', 'discovery', 'chain', 'onchain_progress', 'first_evidence', 'dex_discovery', 'token_images', 'published', 'failed'}
         if event.get('stage') not in allowed: return
         with self.locked():
             job = self.get(job_id)
-            counts = {k: v for k, v in event.items() if k in {'complete_chains', 'candidates', 'tokens','chain_id','registry','checked','held','block_number'} and type(v) is int and v >= 0}
+            counts = {k: v for k, v in event.items() if k in {'complete_chains', 'candidates', 'tokens','chain_id','registry','checked','held','block_number','total'} and type(v) is int and v >= 0}
             job['stage'] = event['stage']
             if event['stage']=='chain' and type(event.get('chain_id')) is int:
                 block=event.get('block_number');block=str(block) if type(block) is int and block>=0 else block
@@ -373,20 +399,41 @@ class JobStore:
                     'endpoint_index':event.get('endpoint_index') if type(event.get('endpoint_index')) is int else None,
                     'status':event.get('status') if event.get('status') in ('complete','partial','unavailable') else 'unknown'}
             job['events'].append({'stage': event['stage'], 'observed_at': now(), 'counts': counts})
+            if event['stage']=='onchain_progress' and event.get('operation') in ('balances','registry','metadata','curves','markets'):
+                job['events'][-1]['context']={'operation':event['operation'],'chain_id':counts.get('chain_id')}
+            if event['stage']=='first_evidence' and event.get('snapshot')==job['checkpoint']+'/initial':
+                saved=self.snapshot(event['snapshot'])
+                wallet=job['input'].get('wallet') or job['input'].get('address')
+                if saved.get('wallet_address','').lower()==wallet.lower():job['result']={'snapshot_id':event['snapshot'],'status':saved['status'],'phase':'initial'}
             if event['stage']=='chain' and type(event.get('chain_id')) is int:job['events'][-1]['context']={'chain_id':event['chain_id'],**job['chains'][str(event['chain_id'])]}
             job['events'] = job['events'][-100:]
             self.save(job)
 
     def set_tags(self, job):
-        registry = read(self.root / 'wallets.json')
-        wallet = next(w for w in registry['wallets'] if w['address_key'] == job['input']['wallet'])
-        old = wallet['tags']; tags = job['input']['tags']
-        for tag in set(old) ^ set(tags):
-            registry.setdefault('tag_history', []).append({'address_key': wallet['address_key'], 'tag': tag,
-                'action': 'add' if tag in tags else 'remove', 'observed_at': now(), 'source': 'operator'})
-        wallet['tags'] = tags; atomic(self.root / 'wallets.json', registry)
+        from wallet import registry_locked
+        with registry_locked(self.root):
+            registry = read(self.root / 'wallets.json')
+            wallet = next(w for w in registry['wallets'] if w['address_key'] == job['input']['wallet'])
+            old = wallet['tags']; tags = job['input']['tags']
+            for tag in set(old) ^ set(tags):
+                registry.setdefault('tag_history', []).append({'address_key': wallet['address_key'], 'tag': tag,
+                    'action': 'add' if tag in tags else 'remove', 'observed_at': now(), 'source': 'operator'})
+            wallet['tags'] = tags; atomic(self.root / 'wallets.json', registry)
         return {'wallet': wallet['address_key'], 'tags': tags, 'status': 'completed'}
 
+    def continue_research(self):
+        """A durable continuation of the admitted analysis, behind initial reports."""
+        for parent in self.list():
+            if parent.get('analysis_phase')!='baseline' or parent['state'] not in ('succeeded','partial') or parent.get('cancel_requested') or parent.get('continuation_id'):continue
+            result=parent.get('result')
+            if not result or not result.get('snapshot_id'):continue
+            saved=self.snapshot(result['snapshot_id'])
+            if saved.get('pipeline',{}).get('phase')!='baseline':continue
+            wallet=parent['input'].get('address') or parent['input'].get('wallet')
+            child=self.submit({'schema_version':1,'operation':'wallet.refresh','input':{'wallet':wallet},'idempotency_key':'enrichment:'+parent['job_id']},phase='enrichment',parent=parent['job_id'])
+            with self.locked():
+                parent=self.get(parent['job_id']);parent['continuation_id']=child['job_id'];self.save(parent)
+
     def engine_command(self, job):
         if job['operation'] == 'prices.refresh':
             command = [sys.executable, str(ASSETS / 'viewer/refresh_prices.py'), '--wallet', job['input']['wallet']]
@@ -394,6 +441,7 @@ class JobStore:
             add = job['operation'] == 'wallet.add'
             command = [sys.executable, str(ASSETS / 'wallet.py'), 'add' if add else 'refresh', job['input']['address'] if add else job['input']['wallet']]
             if add: command += ['--tag', job['input']['tag']]
+            command += ['--phase',job.get('analysis_phase','enrichment')]
             if (self.root / job['checkpoint'] / 'run.json').exists(): command += ['--resume', job['checkpoint']]
         return command
 
@@ -412,7 +460,7 @@ class JobStore:
                     previous=config['rpc']['chains'].get(key,{})
                     if row['url_env']==previous.get('url_env') and previous.get('alchemy_network'):row['alchemy_network']=previous['alchemy_network']
                 config['rpc']=updated
-            elif job['operation']=='settings.discovery':config['discovery']={**job['input'],'explorers':config['discovery'].get('explorers',False)}
+            elif job['operation']=='settings.discovery':config['discovery']={**config['discovery'],**job['input']}
             else:
                 from kira_config import provider_config,secret_values
                 config=provider_config(config,**job['input'])
@@ -420,12 +468,12 @@ class JobStore:
                     raise JobError('connection_key_missing','Kira cannot find the local Alchemy key. Follow the connection guide, then retry. Existing settings are unchanged.')
             atomic(config_path(),config)
             result={'status':'completed','setting':job['operation']};atomic(self.jobs/'results'/(job['job_id']+'.json'),result);return result
-        env = {**os.environ, 'KIRA_DATA_DIR': str(self.root), 'KIRA_JOB_ID': job['job_id'], 'KIRA_JOB_SNAPSHOT': job['checkpoint'], 'KIRA_ANALYSIS_FD': str(writer.fileno()), 'PYTHONUNBUFFERED': '1'}
+        env = {**os.environ, 'KIRA_DATA_DIR': str(self.root), 'KIRA_JOB_ID': job['job_id'], 'KIRA_JOB_SNAPSHOT': job['checkpoint'], 'KIRA_ANALYSIS_FD': str(writer.fileno()), 'PYTHONUNBUFFERED': '1', 'KIRA_RESEARCH_GENERATION':job.get('parent_job_id',job['job_id'])}
         command=self.engine_command(job)
         child = subprocess.Popen(command, env=env, cwd=ASSETS, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
             start_new_session=True, pass_fds=(lease.fileno(), writer.fileno()))
         selector = selectors.DefaultSelector(); selector.register(child.stdout, selectors.EVENT_READ)
-        buffer = b''; cancelled = False; stopped = False
+        buffer = b''; cancelled = False; stopped = False; yielded = False; next_check = 0
         def stop_child():
             nonlocal stopped
             if stopped:return
@@ -445,6 +493,10 @@ class JobStore:
             while child.poll() is None:
                 if self.get(job['job_id'])['cancel_requested']:
                     cancelled = True; stop_child(); break
+                if job.get('analysis_phase')=='enrichment' and time.monotonic()>=next_check:
+                    next_check=time.monotonic()+2
+                    if any(j['state']=='queued' and j.get('analysis_phase')=='baseline' for j in self.list()):
+                        yielded=True;stop_child();break
                 for key, _ in selector.select(.2):
                     chunk = os.read(key.fileobj.fileno(), 65536)
                     if not chunk: selector.unregister(key.fileobj); continue
@@ -467,6 +519,7 @@ class JobStore:
             receipt = self.publication(job)
             if receipt: return receipt
             if cancelled: raise JobError('cancelled', 'Job stopped. Previous published results and saved evidence were preserved.')
+            if yielded:raise JobError('yielded','Detailed research yielded to a new initial report. Saved identity checkpoints are retained.')
             raise JobError('engine_failed', 'Analysis stopped before publication. Check connection settings and resume saved evidence.')
         finally:
             stop_child(); selector.close(); child.stdout.close()
@@ -478,13 +531,18 @@ class JobStore:
             with (self.root / '.analysis.lock').open('a') as writer:
                 fcntl.flock(writer, fcntl.LOCK_EX)
                 self.recover()
+                self.continue_research()
             while True:
                 writer = (self.root / '.analysis.lock').open('a')
                 fcntl.flock(writer, fcntl.LOCK_EX)
                 with self.locked():
-                    queued = sorted((self.get(p.stem) for p in self.jobs.glob('*.json')), key=lambda j: j['created_at'])
+                    queued = sorted((self.get(p.stem) for p in self.jobs.glob('*.json')), key=lambda j: (j.get('analysis_phase')=='enrichment',j['created_at']))
                     job = next((j for j in queued if j['state'] == 'queued'), None)
                     if not job:writer.close();return
+                    if job.get('analysis_phase')=='enrichment':
+                        entry=self.wallet(job['input']['wallet'])
+                        if entry.get('research_generation') not in (None,job.get('parent_job_id')):
+                            job.update(state='cancelled',stage='stopped',errors=[{'code':'superseded','message':'Newer holdings research replaced this detailed run. Earlier evidence is preserved.'}]);self.save(job);writer.close();continue
                     from kira_config import load_config
                     config=load_config()
                     job['provider_configuration']={'rpc_mode':config['rpc']['mode'],'discovery_provider':config['discovery']['provider'],
@@ -494,9 +552,13 @@ class JobStore:
                     result = self.execute(job, lease, writer)
                     with self.locked():
                         job = self.get(job['job_id']); job.update(result=result, state='succeeded' if result['status'] == 'completed' else 'partial', stage='published'); self.save(job)
+                    self.continue_research()
                 except JobError as error:
                     with self.locked():
-                        job = self.get(job['job_id']); job.update(state='cancelled' if error.code == 'cancelled' else 'failed', stage='stopped', errors=[{'code': error.code, 'message': str(error)}]); self.save(job)
+                        job = self.get(job['job_id'])
+                        if error.code=='yielded':job.update(state='queued',stage='queued',errors=[])
+                        else:job.update(state='cancelled' if error.code == 'cancelled' else 'failed', stage='stopped', errors=[{'code': error.code, 'message': str(error)}])
+                        self.save(job)
                 except (Exception, KeyboardInterrupt):
                     with self.locked():
                         job = self.get(job['job_id'])

package/kira_research_tools.py

@@ -51,7 +51,7 @@ class ResearchTools:
             raise JobError('job_scope','Only approved wallet research jobs are available.')
         selector=job['input'].get('wallet') or job['input'].get('address')
         wallet=self.wallet(selector,approved)
-        return {'wallet':wallet,**{key:job.get(key) for key in ('job_id','operation','state','stage','created_at','updated_at','checkpoint','result','chains')}}
+        return {'wallet':wallet,**{key:job.get(key) for key in ('job_id','operation','state','stage','created_at','updated_at','checkpoint','result','chains','analysis_phase','parent_job_id','continuation_id','events')}}
 
     def call(self, name, arguments, key):
         tool=next((row for row in CATALOG if row['name']==name),None)