kira-wallet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kira Wallet contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# Kira Wallet
+
+A local EVM wallet research workspace with Kira and durable research jobs.
+It records direct holdings, Mint Club bonding curves and DEX liquidity evidence.
+Missing coverage and prices stay unknown.
+
+Original code and character assets are open source under MIT. Third-party
+references retain their own terms; see [notices](THIRD_PARTY_NOTICES.md). The npm
+first npm publication is prepared for the operator. No signing, transfers or trades
+are implemented.
+
+## Local installation
+
+Requirements: Node.js 22 or newer and Python 3.11 or newer. macOS is verified.
+Analysis and daemon lifecycle currently require POSIX process and file-lock APIs.
+
+```sh
+npm install --ignore-scripts
+node bin/kira.cjs init
+node bin/kira.cjs doctor
+node bin/kira.cjs setup
+```
+
+The viewer starts at http://127.0.0.1:8787. Data defaults to
+`~/.local/share/kira-wallet`, separate from the installed package. Use
+`--data-dir /absolute/private/directory` before the command for another portfolio.
+The existing workspace viewer can still run at port 8765.
+
+For an isolated sample with synthetic data:
+
+```sh
+node bin/kira.cjs --data-dir /tmp/kira-sample demo --port 8790
+node bin/kira.cjs --data-dir /tmp/kira-sample stop
+```
+
+## Research
+
+```sh
+kira add <operator-supplied-address> --tag '<exact tag>'
+kira refresh '<registered address or tag>'
+kira prices '<registered address or tag>'
+```
+
+From source, substitute `node bin/kira.cjs` for `kira`. Commands create private
+runtime data. The viewer detects local updates within five seconds; it does
+not poll providers. Resume a failed analysis with the same command and
+`--resume <relative snapshot directory>`.
+
+The engine checks official Mint Club deployment scope, discovers indexed held
+tokens when configured, pins chain reads to blocks, enumerates reachable bond
+registries, queries ERC20 and registered ERC1155 token ID 0 balances, records
+curve reserves and burn quotes, and verifies supported DEX pool contracts.
+Shared caches contain asset identities, never another wallet's balances.
+Registry publication is atomic and analysis writers are serialized.
+
+Public RPC can read native balances, known tokens and reachable bond registries.
+General ERC20 discovery requires an indexed provider and successful responses.
+Testnets, pool TVL and shared curve backing are excluded from wallet USD totals.
+Spot value is distinct from an executable redemption estimate.
+
+See [CLI and provider configuration](docs/CLI.md) and
+[viewer behavior](viewer/README.md). Development reports, design concepts and
+generation records remain in the source checkout under `docs/` and `prototype/`.
+
+## Verification
+
+```sh
+npm test
+node --check pipeline-onchain.cjs
+node --check onchain.cjs
+```
+
+UI changes also require responsive browser and keyboard checks. Installation
+checks must use a fresh directory without operator credentials or data.
+
+## Durable local workspace
+
+Development build 0.1.0-dev.2 adds persisted research jobs and opt-in protected
+browser controls. Start with `kira start --controls`; the usual start stays
+read-only. CLI and browser use the same typed job service for research, exact
+wallet names and connection references. Jobs preserve prior results, retain
+partial evidence and require explicit interruption recovery. Price jobs keep
+immutable overlays. Saved analyses can be compared with exact decimal balance
+changes and missing records remain unknown.
+
+`kira tools` is a read-only local MCP adapter, with no automatic account or
+model connection. See [CLI usage](docs/CLI.md), [job contract](docs/JOB_CONTRACT.md),
+[tool setup gate](docs/AGENT_TOOLS.md) and [continuation evidence](docs/KIRA_JOBS_BUILD_REPORT.md).
+
+## Kira research workspace
+
+The workspace places Kira's local briefing and connected conversation
+beside the evidence. The brand link returns Home. Overview, All tokens
+and Activity have distinct tabs; wallet controls stay together. On small
+screens, switch directly between Portfolio and Kira.
+
+All tokens uses existing recorded aggregates with chain-plus-contract identity,
+search, network and pricing filters, and 50 rows per page. It does not query
+providers. Activity separates active work from persisted job history and shows
+state, elapsed time, last progress and recovery controls. Missing progress does
+not silently turn a running job into a completed or failed job.
+
+Run `kira setup` to connect your installed Codex or Claude Code CLI account.
+Choose no wallet context, one registered wallet or the whole portfolio. A real
+response check verifies the selected model before permissions are saved. Drafts
+stay in memory. Kira-local conversation retention is opt-in; provider and native
+CLI policies remain separate. Context or model changes start a fresh conversation.
+Chat does not sign, trade or automatically start research. See the
+[onboarding and conversation contract](docs/ONBOARDING_CHAT_CONTRACT.md), the
+[redesign report](docs/KIRA_REDESIGN_REPORT.md) and
+[agreed wallet capability direction](docs/WALLET_CAPABILITIES.md).
+
+For a contribution, use synthetic data and run `python3 scripts/check-public.py`
+before a push. Never attach a personal portfolio screenshot, registry, snapshot,
+job, credential, local path or log to an issue or PR. Repository history uses a
+public noreply identity. The `kira-workspace-v1` tag preserves the prior UI.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Third-party reference material
+
+Kira's original code and character assets are provided under the root MIT
+license. Third-party reference files retain their original terms. The root
+license does not relicense them.
+
+- `sources/mintclub-multitoken.sol` retains its `BUSL-1.1` SPDX identifier.
+  It is a research reference, not a contract deployed by Kira.
+- `sources/uniswap-state-view.sol` retains its MIT SPDX identifier.
+- Mint Club ABI and contract metadata are research references to
+  [Mint Club](https://github.com/Steemhunt/mint.club-v2-contract).
+- Installed dependencies retain their package licenses. Remote token and chain
+  artwork is referenced from its provider; the app does not claim ownership.

package/bin/kira.cjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Keep the existing read-only Python engine and ship its Node dependency here.
+const {spawnSync}=require('node:child_process');
+const path=require('node:path');
+const result=spawnSync(process.env.KIRA_PYTHON || 'python3',
+  [path.join(__dirname,'../kira_cli.py'),...process.argv.slice(2)],{stdio:'inherit'});
+if(result.error){console.error('Kira needs Python 3.11 or newer. Set KIRA_PYTHON to its executable.');process.exitCode=1;}
+else process.exitCode=result.status ?? 1;

package/curve_pricing.py

@@ -0,0 +1,86 @@
+"""Resolve spot prices through external Mint Club reserve curves."""
+from concurrent.futures import ThreadPoolExecutor
+import json
+import math
+from pathlib import Path
+import subprocess
+import sys
+import research as h
+
+
+def resolve(graph, prices):
+    nodes={(r['chain_id'],r['address'].lower()):r for r in graph if r.get('address')}
+    known={(r['chain_id'],r['address'].lower()):r for r in prices}
+    cache={}
+    def visit(key,seen):
+        if key in cache:return cache[key]
+        if key in seen:return None
+        existing=known.get(key)
+        node=nodes.get(key)
+        if existing and existing.get('usd') is not None and existing.get('quality')!='unreliable':
+            cache[key]=existing;return existing
+        if not node or node.get('error') or not node.get('is_curve'):return None
+        if not node['funded']:
+            return {'chain_id':key[0],'address':node['address'],'usd':None,'basis':'Curve spot','quality':'unfunded'}
+        parent=visit((key[0],node['reserve_token'].lower()),seen|{key})
+        if not parent or parent.get('usd') is None:return None
+        usd=float(node['price_in_reserve'])*parent['usd']
+        if not math.isfinite(usd) or usd<0:return None
+        record={'chain_id':key[0],'address':node['address'],'usd':usd,'basis':'Curve spot','quality':'estimated',
+                'source':node['source'],'observed_at':node['observed_at'],'block_number':node['block_number'],
+                'curve_price_in_reserve':node['price_in_reserve'],'curve_reserve':node['curve_reserve'],'reserve_symbol':node['reserve_symbol'],
+                'price_path':[node['address']]+parent.get('price_path',[node['reserve_token']])}
+        cache[key]=record
+        return record
+    for key in nodes:visit(key,set())
+    return list(cache.values())
+
+
+def enrich(snapshot,market,folder):
+    from wallet import ALCHEMY, DEX, atomic, fetch, pool_row, run_node
+    sys.path.insert(0,str(h.ASSETS/'viewer'))
+    from model import dex_price
+    networks=json.loads((h.ASSETS/'sources/rpc-candidates.json').read_text())
+    input_path=folder/'reserve-graph-input.json'
+    atomic(input_path,{'wallet':snapshot['wallet_address'],'tokens':snapshot['tokens'],'networks':networks})
+    run_node('reserves',input_path,folder/'reserve-graph.json')
+    graph=json.loads((folder/'reserve-graph.json').read_text())['tokens']
+    ordinary=[r for r in graph if r.get('address') and r.get('is_curve') is False and r['chain_id'] in ALCHEMY]
+    prices=list(market.get('tokens',[]))
+    # Only reserve assets are requested. Identify prices by network and contract, never symbol.
+    requests=[{'network':ALCHEMY[r['chain_id']],'address':r['address']} for r in ordinary]
+    inverse={value:key for key,value in ALCHEMY.items()}
+    responses=[]
+    key=h.secrets().get('ALCHEMY_CUSTOM_APY_KEY')
+    for i in range(0,len(requests) if key else 0,25):
+        response=fetch('https://api.g.alchemy.com/prices/v1/'+h.secrets()['ALCHEMY_CUSTOM_APY_KEY']+'/tokens/by-address',{'addresses':requests[i:i+25]})
+        responses.append({'observed_at':h.now(),'source':'Alchemy token prices by address','request':requests[i:i+25],'response':response})
+        for record in response.get('data') or []:
+            p=next((p for p in record.get('prices',[]) if p.get('currency')=='usd' and p.get('value') is not None),None)
+            if p and not record.get('error'):
+                value=float(p['value'])
+                if math.isfinite(value) and value>0:
+                    prices.append({'chain_id':inverse[record['network']],'address':record['address'],'usd':value,'basis':'Market index','quality':'estimated',
+                                   'observed_at':p.get('lastUpdatedAt'),'source':'https://www.alchemy.com/docs/data/prices-api/prices-api-endpoints/prices-api-endpoints/get-token-prices-by-address'})
+    atomic(folder/'reserve-market-prices.json',responses)
+    def get(row):
+        chain=DEX.get(row['chain_id'])
+        if not chain:return None
+        url='https://api.dexscreener.com/token-pairs/v1/'+chain+'/'+row['address']
+        return {'row':row,'source':url,'observed_at':h.now(),'response':fetch(url)}
+    keys={(p['chain_id'],p['address'].lower()) for p in prices if p.get('usd') is not None}
+    missing=[r for r in ordinary if (r['chain_id'],r['address'].lower()) not in keys]
+    with ThreadPoolExecutor(max_workers=4) as executor:fetched=list(executor.map(get,missing))
+    atomic(folder/'reserve-dex-prices.json',fetched)
+    for r in fetched:
+        if not r or not isinstance(r['response'],list):continue
+        row=r['row'];shadow={'token_address':row['address'],'dex_pools':[pool_row(p,r['observed_at']) for p in r['response']],'indexer_price_references':[]}
+        p=dex_price(shadow,r['observed_at'])
+        if p and p.get('usd') is not None:prices.append({'chain_id':row['chain_id'],'address':row['address'],**p})
+    # Keep a supported DEX price for held tokens. Add external curve references for their children.
+    resolved=resolve(graph,prices)
+    by_key={(p['chain_id'],p['address'].lower()):p for p in prices}
+    for p in resolved:by_key[(p['chain_id'],p['address'].lower())]=p
+    market['tokens']=list(by_key.values())
+    market['reserve_price_graph']={'source_file':'reserve-graph.json','observed_at':h.now(),'curve_count':sum(r.get('is_curve') is True for r in graph),'errors':sum(bool(r.get('error')) for r in graph)}
+    return market

package/docs/AGENT_TOOLS.md

@@ -0,0 +1,53 @@
+# Recorded research tools
+
+`kira --data-dir <private-portfolio> tools` serves a read-only MCP adapter over
+newline-delimited JSON on stdin/stdout. Protocol version is pinned to
+2025-06-18. It performs no login, model turn, provider request or research
+mutation. Diagnostics stay out of stdout. The process exits on EOF.
+
+Tools: portfolio_read, wallet_read, token_read, network_read, job_list,
+job_read, snapshot_read and snapshots_compare. Arguments reject extra fields.
+Tokens use chain ID and exact contract, or `native`. Missing records remain
+unknown. Snapshots expose facts and safe source links, with fixed provider
+errors. No arbitrary files, shell commands, credentials or mutation tools are
+available. Local access to this process grants access to the selected portfolio.
+Only connect it to an explicitly chosen client and data directory.
+
+Example client-side stdio configuration, after operator approval:
+
+```toml
+[mcp_servers.kira]
+command = "kira"
+args = ["--data-dir", "<private-portfolio>", "tools"]
+```
+
+Replace the placeholder locally. Do not commit portfolio paths or credentials.
+Kira does not edit the operator's Codex configuration automatically.
+
+## Account connection gate
+
+The browser's Kira notes remain deterministic. Connected chat, OAuth handling
+and conversation reconnect are not delivered by this adapter.
+
+Before connecting a Kira-owned model session, the operator must select the
+account/authentication route and approve which portfolio facts may reach the
+model. The current official ChatGPT-plan app-server guide describes an app-owned
+OAuth access token, Responses provider configuration and token renewal. It does
+not establish this account's eligibility. Client registration, consent and
+login are operator actions. Do not copy desktop authentication files or use the
+internal-only external ChatGPT-token schema variant. No billing claim follows
+from a tool handshake or model catalog.
+
+After the gate, implement the selected auth route and app-server session driver
+with saved thread IDs, terminal turn states, reconnect and interruption. Keep
+those states distinct from engine jobs. Pin the installed protocol again and
+independently review permissions before connecting real private data.
+
+Sources checked on 2026-10-03:
+
+- [Official Codex app-server guidance](https://developers.openai.com/siwc/token-sharing-open-source/codex-app-server)
+- [Official Codex MCP guidance](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
+- [MCP stdio transport contract](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
+
+Local verification uses synthetic portfolios and a stdin transcript only.
+It does not verify a live Codex/MCP client connection or model access.

package/docs/CLI.md

@@ -0,0 +1,144 @@
+# CLI and provider configuration
+
+The npm package carries the Python engine, browser assets and declared viem
+dependency. It needs no Python packages and no sibling project. The package
+file list excludes wallets, snapshots, conversations, caches, logs and private settings.
+The first release is prepared as a tarball. Registry publication remains an
+operator action. The code and original character assets use the MIT license.
+
+## Lifecycle
+
+`kira init` prepares an empty private data directory. `kira start --port 8787`
+starts a loopback-only read-only viewer. `kira status` identifies the managed
+instance. `kira stop` checks its live instance ID and OS process identity.
+Another portfolio never silently reuses that server.
+
+`kira setup` starts the loopback viewer with local controls and opens its setup
+screen. Use `--no-open` to print its URL instead. If a read-only viewer is already
+running, stop it explicitly before setup. The normal `kira start` remains read-only.
+
+## Your model account
+
+Install and sign in to the official Codex CLI or Claude Code CLI first. Kira
+detects the installed binary and native subscription login without copying its
+authentication. Verified adapter versions are Codex 0.158.x and Claude Code
+2.1.259 through 2.1.x. Other versions are blocked until their restrictions are
+verified. This is a native CLI connection, with no Kira account, API-key proxy or
+hosted portfolio backend.
+
+In setup, choose the CLI account and an optional model ID. The blank model field
+uses the CLI default. Choose no automatic wallet context, one registered wallet,
+or the whole recorded portfolio. A generic response check sends no wallet data
+and must pass before these settings are saved.
+
+Your entered message and approved context go through the CLI to its model
+service. Context includes recorded balances, wallet names and addresses, chain
+and contract identities, timestamps, unknown prices and coverage. Credentials,
+RPC endpoints, raw provider errors and local paths are excluded. Changing the
+provider, model, context or selected wallet creates a new conversation.
+
+Kira-local history is opt-in and uses private `conversations/` files. With history
+off, conversations and drafts stay in memory. A new server process starts a fresh
+conversation; saved files remain available locally and are not automatically
+replayed. Native CLI, administrator policy and provider data policies remain a
+separate trust boundary. Chat cannot sign, trade or automatically start research.
+See [the conversation contract](ONBOARDING_CHAT_CONTRACT.md).
+
+Global `--data-dir` precedes the command. `KIRA_DATA_DIR` provides the same
+override. `KIRA_PYTHON` selects Python. Direct historical scripts keep their
+workspace default. The supported CLI uses the user data directory. Installed
+assets and writable runtime files use separate roots.
+
+## Public RPC
+
+```sh
+kira rpc public
+kira discovery none
+kira doctor
+kira doctor --live --chains 1,8453,81457 --budget 30
+```
+
+No credential file is required. Live doctor performs bounded identity, block,
+deployed bond bytecode, Multicall3 bytecode and historical bytecode probes.
+It reports endpoint indexes. These samples do not guarantee broad archive
+history, multicall execution or wallet coverage. Exit code 2 means at least one
+sampled chain is unavailable or limited. Failed endpoints stop after their
+first failure; at most three are tried per chain. There are no hidden retries.
+The budget limits JSON-RPC method calls in that invocation. Full analysis has
+no global request cap yet.
+
+## Custom RPC and discovery
+
+Set an endpoint in your shell or private environment file. Keep the value out
+of command arguments. Configuration stores references only.
+
+```sh
+export KIRA_BASE_RPC='<your HTTPS endpoint>'
+kira rpc set --chain 8453 --url-env KIRA_BASE_RPC
+export ALCHEMY_API_KEY='<your key>'
+kira discovery alchemy --key-env ALCHEMY_API_KEY --explorers
+kira config show
+```
+
+Custom mode disables public fallback by default. Add `--public-fallback` to
+explicitly enable it. That preference applies to all custom-mode chains.
+Chains without a configured endpoint remain unavailable while fallback is
+disabled. Plain HTTP is accepted only for loopback endpoints.
+
+Discovery is independent. Without an indexer, native and reachable Mint Club
+reads still run and general discovery stays incomplete. Configuring an RPC
+does not prove ERC20 discovery completeness.
+
+## Explicit compatibility import
+
+```sh
+kira config import-env --file /absolute/private/rpc.env --key-env ALCHEMY_API_KEY
+```
+
+The import references the file instead of copying keys. It configures Alchemy
+RPC and portfolio discovery separately, with public fallback enabled to match
+the historical engine. Environment overrides the file. Missing files or keys
+produce limited coverage; malformed configuration fails with safe errors.
+The import does not contact providers. Private settings are never served.
+
+Analysis output contains wallet addresses and tags. Keep runtime directories
+outside repositories or ignored. Never publish operator holdings as demos.
+The demo command uses synthetic addresses and sample prices only.
+
+## Durable research and local controls
+
+Normal `kira add`, `kira refresh` and `kira prices` now save a version 1 job
+before running the existing engine. Use `--idempotency-key <stable-key>` to
+retry a submission without duplicating work. Add `--enqueue` to return after
+queuing the job and start a separate worker. `--resume <snapshot-directory>`
+remains the legacy unpublished-snapshot interface. New durable jobs resume by
+job ID:
+
+```sh
+kira jobs list
+kira jobs read <job-id>
+kira jobs cancel <job-id>
+kira jobs resume <job-id> --idempotency-key <stable-resume-key>
+kira jobs run
+```
+
+An interrupted job needs an explicit resume. Published partial results retain
+coverage gaps and require a new refresh to investigate again. Failed and
+cancelled jobs retain their last good result and unpublished evidence.
+`jobs run` starts queued work and reconciles crash receipts; it does not replay
+interrupted jobs. Price jobs retain immutable overlays before updating the
+viewer projection. A viewer stop does not cancel research jobs.
+
+Start with `kira start --controls` to enable protected browser actions. The
+usual start remains read-only. Stop an existing read-only instance before
+starting one with controls. Actions need the local session and same origin.
+The supported URL uses 127.0.0.1. Browser controls offer wallet registration,
+exact names, holdings/price refresh, cancel/resume, saved analysis comparison,
+RPC references and discovery references. The synthetic demo cannot start
+provider research. Enter endpoint credential references in Connections;
+secrets and URLs remain outside the browser.
+
+Use `kira --data-dir <private-portfolio> tools` for the read-only stdio adapter.
+See [the tool guide](AGENT_TOOLS.md) and [job contract](JOB_CONTRACT.md).
+Connected chat still requires the operator's account setup and a later session
+integration. The local development package remains private and unlicensed.

package/docs/JOB_CONTRACT.md

@@ -0,0 +1,111 @@
+# Persisted jobs, version 1
+
+The engine owns financial facts. CLI and protected local browser actions share
+this contract. Chat interruption never cancels an engine job.
+
+## Request and identity
+
+Mutations use `{schema_version: 1, operation, input, idempotency_key}`.
+Supported operations are `wallet.add` (address, exact tag), `wallet.refresh`
+(wallet address or exact tag), `prices.refresh` (same), `wallet.setTags`
+(wallet, exact tags), `job.resume` and `job.cancel` (job_id).
+Read operations are `job.read`, `job.list`, `snapshot.read`, and
+`snapshots.compare`. The portfolio projection retains its existing schema.
+
+Inputs reject unknown fields and invalid identifiers. Wallet selectors resolve
+to a unique registered address before persistence. Ambiguous tags fail.
+Idempotency keys are private, bounded strings. Persist only their SHA-256 hash.
+The hash maps to one job across operations. Reusing it with different normalized
+input fails with `idempotency_conflict`. Terminal duplicate submission returns
+the same job without rerunning providers. Resume requeues the same job ID and
+increments its attempt on execution. Retain the key until the job is removed
+by a future explicit retention policy. Version mismatches fail closed.
+
+## Envelope
+
+Each private `jobs/<uuid>.json` records schema_version, job_id, operation,
+input, request_hash, key_hash, state, attempt, created_at, updated_at,
+sequence, cancel_requested, stage, events, checkpoint, result, errors and
+previous_result. Events contain only allowed stage names and real counts.
+Unknown totals stay null. Result references use paths relative to snapshots/;
+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.
+
+States: queued -> running -> succeeded | partial | failed | cancelled.
+Recovery converts unfinished running jobs to interrupted. Explicit resume may
+move interrupted, failed or cancelled to queued. Succeeded and partial jobs
+retain their result; a new refresh is a new job. Partial is a published result
+with documented coverage gaps, not a failed result or proof of zero holdings.
+
+Updates use private files, replace, file fsync and directory fsync under a
+process lock. One worker owns a portfolio. Existing analysis/config locks
+serialize writers. A worker lease is inherited by its engine child, preventing
+another worker from replaying a still-running orphan engine after a supervisor
+crash. A busy legacy writer leaves the new job queued.
+
+## Publication and recovery
+
+Analysis jobs allocate `snapshots/jobs/<job_id>` before executing. The existing
+engine resumes only matching, unpublished evidence; completed per-chain reads
+retain their recorded blocks. Partial stages retain missing information.
+No global block is invented. Engine publication atomically updates the registry
+pointer after results exist. A saved result plus a matching registry pointer
+or research-history entry is authoritative even if the final manifest update
+was interrupted. A published result whose
+pointer has since moved remains readable from its immutable directory.
+
+Price jobs save an immutable overlay and publication receipt before replacing
+the viewer's market-prices projection. Recovery can finish this projection
+without provider calls. Failed or cancelled work retains previous_result and
+saved evidence. Cancellation stops the subprocess group, waits for the writer
+to release, then records its outcome. If publication won the race, record the
+published result rather than claim it was cancelled.
+
+Provider exception text, URLs and credentials never enter public job events.
+Safe errors use fixed codes and messages. Pinned blocks and coverage remain in
+the engine result. Stage progress is evidence from emitted engine events;
+there is no simulated timer or fabricated percentage.
+
+## Local transport
+
+Writes require the exact loopback Host, same Origin, JSON content type and an
+in-memory session token obtained from the same-origin session endpoint. No
+CORS or credential files are exposed. Session tokens rotate on server restart.
+Bound request size and reject foreign origins and DNS-rebinding Host values.
+The legacy viewer remains read-only unless explicitly launched with --controls.
+Synthetic demo controls never start provider requests.
+
+## Acceptance cases
+
+Synthetic tests cover duplicate requests, key conflicts, invalid versions and
+fields, concurrent submit, restart before execution, interruption before and
+after publication, immutable partial results, previous-result preservation,
+cancel/resume, independent worker leases, snapshot path escape, ambiguous tags,
+unknown values and cross-chain coin identity. HTTP checks cover unauthorized
+writes, foreign origins/Host, malformed bodies and safe static allowlists.
+No operator wallet is analysed by this verification.
+
+## Implemented adapters
+
+`kira_jobs.py` contains typed request and persisted envelope definitions, strict
+operation validation and the worker. `sources/job-envelope-v1.schema.json`
+is the versioned envelope artifact. `sources/job-request-v1.schema.json`
+defines the typed mutation request variants. `settings.rpc` and `settings.discovery`
+are also durable operations; they accept environment references only and share
+the portfolio writer lock. `wallet.setTags` records exact tag changes.
+
+Chain events retain actual endpoint ordinal, configured reference identity,
+status and pinned block as a decimal string. Completed cached chain stages emit
+the same saved block on resume. Recorded stage details stay available in the
+browser. A registry publication receipt is authoritative even if a crash
+precedes the final run manifest update. A completed price overlay can reconstruct
+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.

package/docs/KIRA_JOBS_BUILD_REPORT.md

@@ -0,0 +1,92 @@
+# Kira durable workspace delivery
+
+Completed locally on 2026-10-03 as private development build 0.1.0-dev.2.
+The continuation reached the operator account-connection gate. Connected chat,
+publication and independent release review remain pending.
+
+## Delivered behavior
+
+CLI and opt-in browser controls share versioned typed requests and persisted
+jobs. Same-key retries return one job. Saved work survives a worker restart;
+unfinished engine work requires explicit resume. Published partial results
+remain available and cannot be resumed over their immutable analysis. Failure
+and cancellation preserve the previous published result and saved evidence.
+Cancellation terminates the engine process group, including descendants.
+A worker lease survives a supervisor crash while its engine is still active.
+
+Analysis publication reconciles the registry/manifest crash boundary without
+rerunning providers. Price jobs keep an immutable overlay before replacing the
+viewer projection; restart can finish that projection without provider calls.
+Recorded stages retain actual counts, endpoint identity references and decimal
+pinned blocks. Model interruption is separate from engine cancellation.
+
+The browser provides wallet registration, exact names, holdings and price
+refresh, stop/resume, saved analysis comparison and separate RPC/discovery
+references. Host, Origin, session, content type and request-size checks protect
+local actions. Session tokens rotate with the server. The usual launch stays
+read-only; `--controls` explicitly enables actions. The primary local instance
+now has controls enabled. Synthetic demo research cannot contact providers.
+
+The first-wallet screen and connection forms keep unknown values visible.
+Comparison preserves decimal quantities, chain/contract identity and absent
+records as unknown. It reports balance, reference and coverage differences;
+it does not attribute USD changes or compare historical price-overlay values.
+
+The local read-only MCP adapter exposes eight typed tools through `kira tools`.
+It reads recorded facts and jobs without a login, model turn, shell tool or
+provider request. Its stdio transcript and packaged runtime are verified;
+live client attachment is not yet verified.
+
+Kira's new original character icon appears in the brand home link, Home button,
+notes, empty state, wallet dialog and concept studio. Browser and touch icons
+are installed. A tiny editable notebook mark complements the adult portrait.
+Built-in imagegen produced the master and cleaned its transparent exterior.
+[Exact prompts and provenance](character/brand-generation.json) are saved.
+
+## Verification evidence
+
+| Check | Result and scope |
+| --- | --- |
+| `npm test` | Passed 41 engine/configuration/job/tool tests and 24 viewer/HTTP tests, Node cache/outage checks and both viewer JavaScript syntax checks |
+| Node syntax | Passed pipeline-onchain.cjs, onchain.cjs and prototype/app.js |
+| `python3 scripts/check-install.py` | Passed fresh npm pack/install without operator configuration; logo route, read-only lifecycle, protected controls, actual synthetic names job and stdio tool facts |
+| Durable process cases | Passed supervisor SIGKILL recovery with one engine invocation; cancellation stopped a SIGTERM-resistant descendant and preserved prior evidence; publication won a simultaneous cancellation |
+| Browser interaction | Passed actual synthetic names mutation and completion; saved analysis comparison displayed 100 -> 120 with exact delta 20; invalid onboarding address blocked before submission; connection settings separated RPC from discovery |
+| Responsive and keyboard | Checked desktop, 320 px Home/wallet/history and 375 px add form; no document overflow; Escape closes dialogs and returns to the trigger |
+| Preservation | All 682 original runtime JSON hashes unchanged; primary portfolio `/api/state` bytes unchanged across upgrade |
+| Privacy | Source/package allowlists and audit exclude operator registry, snapshots, settings, jobs, logs, authentication and real portfolio screenshots |
+| Independent review / model access | Not performed; no account connection, live Codex/MCP-client attachment, model turn or release claim |
+
+All research tests used synthetic portfolios and local subprocesses. No new
+operator wallet, holdings refresh, price refresh or additional JSON-RPC probe
+was performed in this continuation.
+
+## Open the result
+
+Primary local workspace: `http://127.0.0.1:8765/#/home`.
+Synthetic control preview: `http://127.0.0.1:8793/#/home` while its server runs.
+The empty first-launch preview used a separate private directory at port 8794.
+The original concept studio remains available at port 8792 while running.
+
+![Synthetic workspace with Kira branding and saved job](screenshots/kira-jobs-desktop.jpg)
+
+## Operator boundary and limits
+
+The operator must choose an approved account/authentication route and consent
+to the portfolio scope before connected Kira chat. The current official
+[app-server guide](https://developers.openai.com/siwc/token-sharing-open-source/codex-app-server)
+describes app-owned OAuth handling. This does not establish this account's
+eligibility or billing. The [tool guide](AGENT_TOOLS.md) records the concrete
+setup boundary. No desktop authentication files were copied or used.
+
+Independent security/release review, platform testing beyond macOS, a global
+provider-call cap and an external pilot remain outstanding. Legacy direct
+engine scripts keep their earlier interfaces; immutable price history is
+provided by the durable CLI/browser job path. Read-only model tools do not
+automatically connect a client. Full connected chat and session persistence
+remain future work after account setup. This package remains private and
+unlicensed. No remote, PR, merge, main push, package publication or deployment
+was created.
+
+[Selected design evidence](https://www.lazyweb.com/agentic-search/b98ba70d-d7d2-408b-b6b0-f529201e4365)
+informed the per-job state and recovery UI. It is not a growth or demand claim.