@danceiny/gotry 0.0.1-rc.17 → 0.0.1-rc.19

package/README.md

@@ -2,100 +2,79 @@
 
 # GoTry
 
-[![CI](https://github.com/Danceiny/gotry/actions/workflows/ci.yml/badge.svg)](https://github.com/Danceiny/gotry/actions/workflows/ci.yml)
-
 > **Body and soul — more travel, less tourism.**
 > *身体和灵魂,更多旅行,更少旅游。*
 
-**GoTry is an AI travel agent for "departure to next departure."** You say where you want to go and why; it asks about your working hours and existing bookings, then hands you a **formally verified itinerary** — computed by a solver, not guessed by a model.
-
-| | |
-|---|---|
-| **Version** | `v0.0.1-rc.13+` (npm `latest`; [release notes](docs/release-notes.md)) |
-| **Runtime** | DeepSeek Harness **0.1.2-alpha.3** (root-pinned; [upstream](https://github.com/deepseek-ai/DeepSeek-Harness)) · Z3 WASM · Cordis |
-| **License** | **MIT** ([LICENSE](LICENSE)) |
-| **Docs** | English (this file) · [简体中文 README](README.zh-CN.md) · deep engineering docs are Chinese-first ([docs/architecture.md](docs/architecture.md)) |
+GoTry is an AI travel agent for **"departure to next departure."** You tell it where you want to go and why; it interviews you about your working hours and existing bookings, then hands you a **formally verified itinerary** — computed by a Z3 solver, not guessed by a model.
 
----
+[![CI](https://github.com/Danceiny/gotry/actions/workflows/ci.yml/badge.svg)](https://github.com/Danceiny/gotry/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@danceiny/gotry)](https://www.npmjs.com/package/@danceiny/gotry)
+[![License: MIT](https://img.shields.io/badge/License-MIT-informational)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A5%2022.15-blue)](https://www.npmjs.com/package/@danceiny/gotry)
+[![Docs](https://img.shields.io/badge/docs-architecture.md-blue)](docs/architecture.md)
 
-## ⚡ 30-second start
+**[What GoTry Does](#what-gotry-does)** · **[How It Works](#how-it-works)** · **[Tools](#tools)** · **[Demo](#demo)** · **[Benchmark](#how-mainstream-ai-answers-the-same-trip)** · **[Quick Start](#quick-start)** · **[Consent and Privacy](#consent-and-privacy)** · **[Trustworthy by Construction](#trustworthy-by-construction)** · **[Project Status](#project-status)** · **[Roadmap](#roadmap)** · **[For AI Agents](#for-ai-agents)** · **[Documentation](#documentation)** · **[License](#license)**
 
-```bash
-npx @danceiny/gotry web
-# First run creates .env: LLM_API_KEY=<DeepSeek key, or OpenAI-compatible key>
-#   Not using DeepSeek directly? Also set LLM_BASE_URL=<your endpoint, usually ending in /v1>
-#   Need a specific model (relays often do)? Set LLM_MODEL=<model name> — it drives the
-#   dsh chat face (web/headless) and overrides any model picked in the dsh web settings.
-# → open http://127.0.0.1:3080 and chat: "I want three relaxing days in Dali"
-```
+> **Tip for newcomers:** one command is enough to feel the difference — `npx @danceiny/gotry web`, open `http://127.0.0.1:3080`, and say *"I want three relaxing days in Dali."* The agent interviews you first; then the solver, not the model, decides what is feasible. Full walkthrough: [`docs/user-guide.md`](docs/user-guide.md).
 
-> **Switching models / providers?** The price table (`ts/data/llm-price-table.json`, schema `gotry_llm_price_table_v2`) is the single source of truth for `gotry_m3_nightly_run_v1.cost_usd`. Adding a new model or switching relay = update this file via PR (ADR-11, peak-conservative upper bound only)
-- . Unknown models **fail-closed** — no guessed prices. Drift monitor: `npx tsx ts/scripts/price-drift-watch.ts` (offline baseline diff;
-- `--fetch` for live official pages). Never auto-applies changes.
+## What GoTry Does
 
-| You want | Command |
-|---|---|
-| 🖥️ Conversational planner (recommended) | `npx @danceiny/gotry web` → chat UI on :3080 |
-| 🤖 Scripted / one-shot answer | `npx @danceiny/gotry "Two recovery days from Shenzhen, budget 3000"` |
-| 🛠️ Developer: run from source | see [source install](#%EF%B8%8F-developer-source-install) below |
+GoTry turns "I want to go somewhere" into "can I — and how, at what true cost?" When the answer is "not this weekend," the destination is caught in a wish pool with its conditions instead of being dropped.
 
-- Requires Node 22.15+ and one LLM API key. Any OpenAI-compatible endpoint (MiniMax / relays / self-hosted gateways) works too — add `LLM_BASE_URL` to `.env` (usually ends with `/v1`, e.g. `https://api.minimax.io/v1`) and requests follow it instead of the DeepSeek default. To pin the model,
-  - set `LLM_MODEL` (e.g. `MiniMax-M2`): it applies to both the dsh chat face and the repo scripts, and beats the model selection persisted in the dsh web UI;
-  - unset, the dsh built-in default (`deepseek-v4-flash`) or your web-UI choice is used. Zero-config startup — the dsh runtime is mounted automatically via a cordis patch.
+- **For travelers** — a conversational planner that asks the questions that actually matter (working window, booked resources, departure city, budget), then returns a verdict per destination: feasible or not, why, and the **smallest change that makes it feasible**.
+- **For agent builders** — a working example of an agent where the LLM only listens, translates, and explains. Decisions and arithmetic live in a Z3 solver; every deliverable number carries a provenance tag; write operations are gated by design.
+- **Evidence built in** — an estimate never poses as realtime. Tags are attached by the render layer, never by the model, and switch honestly on degradation. Bookable claims that cannot trace to an exact-date tool result are blocked before delivery.
 
----
+## How It Works
 
-## ✨ What it does
-
-GoTry turns "I want to go somewhere" into "can I, how, and at what true cost":
+One planning pass is a pipeline. The model owns the two language-heavy ends; the solver owns everything numeric:
 
 | Stage | Who | Output |
 |---|---|---|
-| **Motivation interview** | LLM | Mandatory questions: working window / booked resources / departure city |
-| **Fact extraction** | LLM | Working hours semantics, leave semantics |
-| **Feasibility verdict** | **Z3 solver** | Which destinations are feasible / infeasible, why, and the **smallest change that makes them feasible** |
-| **Door-to-door true cost** | Solver | Real flight duration (incl. time zones) + early-wake penalty + transfer cost + arrival energy % |
-| **Evidence chain** | Render layer | Every number carries a **source tag**: `[骨架:openflights]` = route existence verified against the public route database; `[实时API:flyai]` = pulled live from an API seconds ago; `[静态包:估算]` = a researched estimate (**not realtime — verify before booking**). On degradation the tag switches honestly — an estimate never poses as realtime |
-
-**Unlike a regular AI chat**, the LLM only translates and explains. **Decisions and arithmetic are computed by a Z3 solver**, not guessed.
+| Motivation interview | LLM | Mandatory questions: working window / booked resources / departure city |
+| Fact extraction | LLM | Working-hours semantics, leave semantics |
+| Feasibility verdict | **Z3 solver** | Which destinations are feasible / infeasible, why, and the smallest change that makes them feasible |
+| Door-to-door true cost | Solver | Real flight duration (incl. time zones) + early-wake penalty + transfer cost + arrival energy |
+| Evidence chain | Render layer | Every number carries a source tag |
+| Delivery gate | Fact gate | Bookable claims must trace to exact-date tool results, or the artifact is blocked |
+| Memory | Domain layer | Infeasible today → wish pool, with explicit recall conditions |
 
----
+Vocabulary you will meet in a GoTry answer:
 
-## 🚀 Quick start
+- **Evidence tag** — `[skeleton:openflights]` route existence verified against the public route database; `[realtime:...]` pulled live from an API seconds ago; `[static-pack:estimate]` a researched estimate — not realtime, verify before booking. On degradation the tag switches honestly.
+- **Door-to-door true cost** — the ticket price plus what the trip actually takes from you: real duration across time zones, the early-wake penalty, transfers, and the energy you land with.
+- **Wish pool** — "next departure" storage. An infeasible dream is saved with explicit conditions (e.g. "5+ days, off-season") and recalled when they can be met.
+- **Fact gate** — pre-delivery check on itinerary artifacts: every bookable claim (flight no. / time / airport / price / policy) must trace to an exact-date tool result; unverifiable means blocked — never presented as a verified plan.
 
-### One-liner (npm, recommended)
+Architecture, five layers:
 
-```bash
-npx @danceiny/gotry web
 ```
-
-That's it — the dsh chat UI on `:3080` with the GoTry persona mounted. First cold start is 6–15 s; if port `:3080` is taken, free it first; unexpected exits leave evidence in `gotry-state/incidents.jsonl` (nothing silent).
-
-### Developer source install
-
-```bash
-git clone https://github.com/Danceiny/gotry && cd gotry
-npm ci && npm --prefix ts ci                      # ① install the pinned root/TS closure
-node scripts/build-dist.mjs                       # ② build the source checkout's JS runtime
-cp .env.example .env                              # ③ set LLM_API_KEY (+ LLM_BASE_URL if not on DeepSeek; + LLM_MODEL to pin the model)
-./gotry web                                       # ④ in-repo entry, same UX
+┌──────────────────────────────────────────────────────────────┐
+│ L1  chat-as-interface; gates are in-message choice cards       │
+│ L2  orchestration  dsh runtime + GoTry plugin (ReAct); 21 tools│
+│ L3  domain  unified itinerary model + Z3 feasibility engine    │
+│ L4  data  static packs + hotelbyte-cli bridge + OpenFlights    │
+│ L5  governance  LoopX (objective / gates / evidence / quota)   │
+└──────────────────────────────────────────────────────────────┘
 ```
 
-| Entry | Command | When |
+| Layer | Module | Role |
 |---|---|---|
-| dsh Web chat (recommended) | `./gotry web` | multi-turn planning with visualized reasoning → :3080 |
-| headless one-shot | `./gotry "one full task"` | scripts / CI / targeted debugging → stdout |
+| L2 | `ts/src/index.ts` (dsh plugin) | 21 tools, time-anchor & memory-brief variables; execute isolation + consent gate + per-turn tool budget + process guards |
+| L3 | `ts/src/unified.ts` · `py/gotry_feasibility/` | single solving entry (candidate enumeration + flight-chain Z3) |
+| L4 | `ts/capabilities/effect.ts` · `hbcli.ts` · `skeleton-check.ts` | effect interpreter (backoff retry / circuit breaker / mock interpreter) + realtime inventory bridge + OpenFlights skeleton (three-valued semantics) |
+| L5 | loopx governance | objective / gates / evidence / quota |
 
-The source entry and npm package both resolve one 216-package DSH `0.1.2-alpha.3` closure declared as exact direct dependencies. The manifest, package lock, and root pnpm importer must expose the same 216-name set; publish preverify rejects omissions, mixed versions, and ranges. Source checkout runs dsh from `ts/dsh-runtime/` in normal mode so `gotry-state/` continuity is preserved; benchmark opt-in and npm-package runs use the invocation directory for isolation. The old `ts/dsh-runtime/` vendor tree remains a non-benchmark legacy resolution fallback, not a promised runnable path or the recommended install path.
+> Full ADRs / evolution / debt ledger: [`docs/architecture.md`](docs/architecture.md) (Chinese — English versions planned for v0.1.0).
 
----
+## Tools
 
-## 🧰 21 tools
+22 tools in six groups:
 
 | Group | Tool | What it does |
 |---|---|---|
-| **Realtime retrieval (OTA/official, read-only)** | `gotry_flyai_search` | Live flight/train/hotel quotes via the Fliggy official channel (masked hotel prices upstream; real prices on the jumpUrl page) |
-| | `gotry_session_search` | Ctrip flights on the **user's own logged-in Chrome session** (consent-gated, physically read-only) |
+| **Realtime retrieval (OTA/official, read-only)** | `gotry_flyai_search` | Live flight/train/hotel quotes via the Fliggy official channel (masked hotel prices upstream; real prices on the jumpUrl page; exhausted anonymous trial quota degrades as `needs-setup` with key guidance, never silent retries) |
+| | `gotry_session_search` | Ctrip flights **and hotels** + 12306 trains on the **user's own Chrome session** (consent-gated, physically read-only; hotels = `kind:"hotel"` + optional `cityId`, real logged-in prices; trains = `kind:"train"`, public query face — codes/times/seat availability, no prices in the list API) |
 | | `gotry_session_login` | Login bootstrap: auto-detects existing login first; otherwise opens the login entry in the user's Chrome (**zero terminal**) |
 | | `gotry_weather_check` | Open-Meteo forecast ≤16 d + historical climate baseline |
 | | `gotry_flight_verify` | OpenSky ADS-B live flight observation (three-valued) |
@@ -107,26 +86,13 @@ The source entry and npm package both resolve one 216-package DSH `0.1.2-alpha.3
 | | `gotry_wish_pool_add` / `gotry_wish_pool_list` | "next departure" wish pool + 0..1 conditional recall |
 | | `gotry_companion_save` · `gotry_trip_log` | companion profile / travel timeline |
 | **Artifacts** | `gotry_artifacts_list` / `gotry_artifacts_read` | Discover & view generated artifacts (async deliverables + working-dir markdown) as a line-numbered file view (read-only) |
-| **Factuality gate** | `gotry_fact_gate` | Pre-delivery gate for itinerary artifacts: every bookable claim (flight no./time/airport/price/policy) must trace to an exact-date tool result (hit AND miss recorded); unverifiable ⇒ blocked — never present as a verified plan |
+| **Factuality gate** | `gotry_fact_gate` | Pre-delivery gate for itinerary artifacts — see [fact gate](#how-it-works) above |
 | **General external** | `gotry_web_search` · `gotry_video_subtitle` · `gotry_github_search` · `gotry_agent_reach` | web / subtitles / GitHub / all-channel external info (via Agent-Reach) |
+| **Self-check** | `gotry_doctor` | Read-only health check of optional dependencies (extension / Agent-Reach .venv / hbcli / FlyAI key **+ recent trial-quota exhaustion time** / dsh-calendar mount state / sidebar / dsh-map-tools & dsh-tool-ask-user presence) with exact repair guidance; installs only ever happen via the user running `npx gotry doctor --fix`. LLM keys are the dsh host's business — deliberately out of scope. Report lands in `gotry-state/doctor-report.md` (sidebar-workbench previewable) |
 
----
-
-## 🔐 Account session: consent & privacy
-
-The account session channel reads realtime hotel/flight data from **the user's own logged-in Chrome**, under four hard rules:
+> **Channel routing**: retrieval tools stay flat (no hidden dispatch); the persona routing card and the `routing` suggestions attached to failed search results are **generated from one channel registry** (official API > user session > web fallback, filtered by per-session channel health). When a channel exhausts its quota the result says so and names the next channel — retry-blindness is a contract violation, not a prompt hope.
 
-1. **Login happens on the external website.** GoTry never offers, fills, or collects any password / SMS code / cookie value. It only answers one boolean question: "does a login-ticket cookie exist" (reads cookie **names** only — zero values touched).
-2. **Consent card, once per session.** The first account-session use pops a runtime approval card; approval holds for the session, a refusal revokes it for the session (no repeat prompting). Master switch `sessionAccess: ask|allow|off` at any time.
-3. **Physically read-only.** A ReadGuard aborts all write requests at the network layer (ordering/payment is unreachable in transport); the agent never touches credentials or captchas — on a captcha it stops and hands control back.
-4. **Never hijacks your browser.** Retrieval/login always open their own dedicated tab; the login page is brought to front and stays with you; routine test runs never open browser windows.
-
-> One-time prerequisite: install the [GoTry Session Bridge](https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd) Chrome extension from the Chrome Web Store (one click, auto-updates) — done in the browser, not by gotry. Review-free GitHub-channel fallback is optional; for that variant see [`docs/extension-webstore-submission.md`](docs/extension-webstore-submission.md). Zero Chrome system dialogs afterwards — the extension passively forwards the site's own search responses (read-only by construction;
-- cookies are read by NAME only, values never leave the browser). Until installed, tools return `needs-extension` with the store URL as a clickable link and spend nothing. (A `cdp` fallback via `chrome://inspect` remote debugging still exists for diagnostics: `GOTRY_SESSION_TRANSPORT=cdp` — note Chrome 144+ shows a permission box on every connection.)
-
----
-
-## 🎬 A conversation — Demo
+## Demo
 
 ```
 > Two or three days staring at Erhai Lake, leaving from Shanghai, budget 3000, annual leave — no work.
@@ -146,105 +112,176 @@ Engine verdict:
 [static-pack:estimate] G7315/G7316 priced on Jul–Aug off-season rates
 ```
 
-> Tag guide: `[骨架:openflights]` means "this route can be flown" was verified against the public route database; `[实时API:*]` marks data pulled live seconds ago; `[静态包:估算]` flags an off-season estimate — **verify before booking**. Tags are attached by the render layer, never by the model.
+> Tag guide: `[skeleton:openflights]` means "this route can be flown" was verified against the public route database; `[realtime:...]` marks data pulled live seconds ago; `[static-pack:estimate]` flags an off-season estimate — **verify before booking**. Tags are attached by the render layer, never by the model.
 
----
+## How Mainstream AI Answers the Same Trip
 
-## 🏛️ Architecture
+GoTry's product persona is calibrated against evidence, not taste: the same real three-week multi-country workation prompt — with planted traps (no year given, a vague "some seaside town called Wan-xx", an ambiguity the user already resolved) — is fed verbatim to mainstream assistants, their answers archived word-for-word, and scored against a ground-truth rubric. Transcripts, rubric, and the contract feedback: [`docs/persona-bench/`](docs/evaluation/persona-bench/).
 
-```
-┌──────────────────────────────────────────────────────────────┐
-│ L1  chat-as-interface; gates are in-message choice cards       │
-│ L2  orchestration  dsh runtime + GoTry plugin (ReAct); 21 tools│
-│ L3  domain  unified itinerary model + Z3 feasibility engine    │
-│ L4  data  static packs + hotelbyte-cli bridge + OpenFlights    │
-│ L5  governance  LoopX (objective / gates / evidence / quota)   │
-└──────────────────────────────────────────────────────────────┘
+| Dimension | Generic chat assistant (Kimi, 13 real turns) | OTA agent (Fliggy open platform, single turn) | GoTry contract |
+|---|---|---|---|
+| Calendar grounding | ✗ 2025 calendar; three user corrections, three apology-refits | ✗ derived weekdays land on the 2025 calendar — contradicting its own answer on the same page | (2)(8)(9) + time-anchor card |
+| Constraint interview | ✗ zero questions; both load-bearing constraints surfaced by the user at turn 6 | △ asks sales qualifiers (budget / star level / sea view); zero must-asks | (1)(10) |
+| Feasibility & time accounting | ✗ density illusion, caught by the user | ✗ HK errands + same-day flight with no time budget; an "8h" flight contradicting its own arrival time | (4) + door-to-door true cost |
+| Fact provenance | △ destination research holds up | ✗ sells a defunct airline (retired 2020); every price unsourced | (3)(7)(13)(20) |
+| Structure completeness | △ decent comparison table only at turn 13 | ✓✓ full skeleton in one turn — completeness is table stakes | verified completeness (fact gate) |
+| Persona in one line | erudite but stateless chatter — the user ends up doing four jobs | a flawless-brochure OTA clerk — every section ends in a price table | trusted travel engineer: interview first, the solver decides, infeasible says infeasible |
+
+**Single best finding: two unrelated products derived their weekdays from the 2025 calendar.** Calendar grounding has to be a product mechanism (anchor card, assert once, never recompute) — not model luck. Cautionary deep-dive: [`docs/research/kimi-postmortem.md`](docs/research/kimi-postmortem.md).
+
+## Quick Start
+
+### npm (recommended)
+
+```bash
+npx @danceiny/gotry web
+# → open http://127.0.0.1:3080 and chat: "I want three relaxing days in Dali"
+# LLM key & model: handled by the dsh host UI; nothing for gotry to ask on the CLI
 ```
 
-| Layer | Module | Role |
+| Entry | Command | When |
 |---|---|---|
-| L2 | `ts/src/index.ts` (dsh plugin) | 21 tools, time-anchor & memory-brief variables; execute isolation + consent gate + per-turn tool budget + process guards |
-| L3 | `ts/src/unified.ts` · `py/gotry_feasibility/` | single solving entry (candidate enumeration + flight-chain Z3) |
-| L4 | `ts/capabilities/effect.ts` · `hbcli.ts` · `skeleton-check.ts` | effect interpreter (backoff retry / circuit breaker / mock interpreter, issue #16) + realtime inventory bridge + OpenFlights skeleton (three-valued semantics) |
-| L5 | loopx governance | objective / gates / evidence / quota |
+| Web chat (recommended) | `npx @danceiny/gotry web` | multi-turn planning with visualized reasoning → `:3080` |
+| Headless one-shot | `npx @danceiny/gotry "Two recovery days from Shenzhen, budget 3000"` | scripts / CI / targeted debugging → stdout |
+| Dependency doctor | `npx @danceiny/gotry doctor` (`--fix` to repair) | optional channels misbehaving: checks extension / Agent-Reach / hbcli / FlyAI key / sidebar / dsh-calendar mount / dsh-map-tools & dsh-tool-ask-user presence, prints exact repair guidance, writes `gotry-state/doctor-report.md` (previewable in the sidebar workbench) |
 
-> 📖 Full ADRs / evolution / debt ledger: [`docs/architecture.md`](docs/architecture.md) (Chinese — English versions planned for v0.1.0)
+Requires Node ≥ 22.15. LLM credentials are managed by your dsh host UI — gotry itself never asks for or echoes them. OpenAI-compatible endpoints (MiniMax / relays / self-hosted gateways) are handled by the dsh model configuration. First cold start takes 6–15 s; if port `:3080` is taken, free it first; unexpected exits leave evidence in `gotry-state/incidents.jsonl` (nothing silent).
 
----
+> **Cost accounting** — `ts/data/llm-price-table.json` (schema `gotry_llm_price_table_v2`) is the single source of truth for nightly run cost. Adding a model or switching relays = a PR against this file (peak-conservative upper bounds only); unknown models **fail closed** — no guessed prices. Drift monitor: `npx tsx ts/scripts/price-drift-watch.ts` (offline baseline diff; `--fetch` for live official pages). It never auto-applies changes.
+
+> **Quality metrics (repo-side)** — `npx tsx ts/scripts/build-metrics-report.ts [--state-root <root>] [--out report.md] [--days 7]` aggregates the persisted sidecars (fact-gate verdict distribution & blocked rate, channel down/cooldown, incidents, bridge latency vs the 500 ms re-audit budget, ledger / doctor-report presence) into one read-only markdown report. No new dependencies, zero LLM; the state root is never written (only `--out` produces a file, outside the state root).
 
-## ⚠️ Status & limitations
+> **Channel probe tick (out-of-band health)** — `npx tsx ts/scripts/channel-probe.ts --state-root <root>` runs one read-only probe round over headless-probeable channels (hbcli whoami / open-meteo / opensky; session surfaces are skipped, FlyAI is not probed by default to preserve the shared anonymous quota) and appends `down` / `'ok'` recovery events to `channel-health.jsonl` — routing advice and doctor pick them up with zero changes. Driven by cron/loopx; no resident process. Wish recall consumes the same facts: a wish whose `conditions.channels` names a currently-down channel is vetoed for that recall. Remote (world2agent) callback stays gated on D-31.
 
-Evaluation Phase 0 foundation boundary: contracts/registry/validators/unmatched diagnostic fixtures/test-only aggregate admission plus a deterministic PR/nightly/weekly/milestone cadence policy/planner. It returns admission, `pass^k`, budgets, calibration, failure-registry, and cross-benchmark synthesis obligations only; it does not schedule or launch adapters, spend, generate a benchmark score, create an Agent optimization round, or support an uplift claim. No external runner, Python runtime dependency, baseline, or matched production evidence is included.
+### Developer source install
+
+```bash
+git clone https://github.com/Danceiny/gotry && cd gotry
+npm ci && npm --prefix ts ci                      # pinned root/TS closure
+node scripts/build-dist.mjs                       # build the JS runtime
+./gotry web                                       # in-repo entry, same UX
+```
+
+The source entry and the npm package resolve the same 216-package DeepSeek Harness `0.1.2-alpha.3` closure (exact direct dependencies; publish preverify rejects omissions, mixed versions, and ranges). Source normal runs keep their state under `ts/dsh-runtime/gotry-state/`; benchmark opt-in and npm-package runs use the invocation directory for isolation.
+
+## Consent and Privacy
+
+The account-session channel reads realtime hotel/flight data from **your own logged-in Chrome**, under four hard rules:
+
+1. **Login happens on the external website.** GoTry never offers, fills, or collects any password / SMS code / cookie value. It only answers one boolean question — "does a login-ticket cookie exist" (reads cookie **names** only, zero values touched). Existing logins are auto-detected with zero popups.
+2. **Consent card, once per session.** The first account-session use pops a runtime approval card; approval holds for the session, a refusal revokes it (no repeat prompting). Master switch `sessionAccess: ask|allow|off` at any time.
+3. **Physically read-only.** A ReadGuard aborts all write requests at the network layer — ordering/payment is unreachable in transport. The agent never touches credentials or captchas; on a captcha it stops and hands control back to you.
+4. **Never hijacks your browser.** Retrieval/login always open their own dedicated tab; the login page is brought to front and stays with you; routine test runs never open browser windows.
+
+One-time prerequisite: the [GoTry Session Bridge](https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd) Chrome extension — handled by the dsh host UI when an account-session tool first needs it (`gotry_session_search` surfaces the install URL as a clickable link in the verdict). The extension itself is one-click on the Chrome Web Store, auto-updates, and the gotry side never asks the user to load unpacked or to run a setup wizard. Zero Chrome system dialogs afterwards — the extension passively forwards the site's own search responses (read-only by construction; cookies are read by NAME only, values never leave the browser). A background health-watch auto-replays your query once the extension is connected. Until installed, tools return `needs-extension` with the store URL and spend nothing.
 
-**Working today** (full-stack regression §1–§34 green; every item has deterministic tests):
+## Trustworthy by Construction
 
-- **Z3 solving engine** — feasibility verdicts + door-to-door whole-cost; the historical concurrency race is fixed (§30 regression gate)
-- **Realtime retrieval** — flight/train/hotel (Fliggy official channel), destination/hotel catalogs, weather, live flight observation, route connectivity; realtime prices can overwrite solver prices (`GOTRY_REALTIME_PRICING=1`)
-- **Account session search** — Ctrip flights on your own logged-in Chrome; consent & privacy rules above (see 🔐 **Account session: consent & privacy**)
-- **One-time browser extension setup** — install [GoTry Session Bridge](https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd) from the Chrome Web Store (a browser concern, not a gotry one — one click on "Add to Chrome"). When `gotry_session_search` returns `needs-extension`, the verdict surfaces the store URL as a clickable link in the dsh UI; the background health-watch auto-replays your query once the extension is connected — no manual retry needed.
-- **Extension distribution (issue #21, ADR-21)** — three channels, same extension: the [Chrome Web Store](https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd) (recommended: one-click install + auto-update; live since 2026-09-02) is what dsh users should rely on; the review-free GitHub Releases channel is an opt-in escape hatch; the npm-bundled copy stays the offline-deterministic fallback;
-  - any GitHub-channel failure falls back to the bundled copy. The store re-signs with its own key, so the store build's extension ID differs from the fixed-key unpacked ID — the local bridge trusts both origins (§38 regression).
-- **Session data cross-verification (issues #21 / #67)** — 8 benchmark queries (sf-01..sf-08) verified end-to-end: 7/8 verdict=hit, 6/6 manual-golden soft-score 100%, all hits <15s, zero ReadGuard writes. The comparator is pluggable: `--golden=manual` (default), `--golden=flyai`,
-  - or `--golden=static`. Static mode pins an ODbL OpenFlights route/carrier snapshot and combines it with manual time/price bands;
-  - evidence records requested vs effective source, provenance, estimated fields, and fallback reason. Snapshot/route failure prints a warning to stderr and falls back to manual. Static mode is deterministic benchmark data, **not live schedule, fare, or availability**.
-- **Observed static-source runs (2026-08-30, logged-in Chrome)** — two consecutive runs produced static official 8/8 with zero fallback each time;
-  - Ctrip session hits varied from 3/8 to 5/8, while every scored hit across both runs (3+5 records) passed 13/13 (100%). Non-hits remain explicit `miss` records,
-    - so the ≥90% field score is not presented as 8/8 live availability. The same runs exposed and fixed an online-extension lifecycle bug: idle parked timers/sockets no longer pin the default CLI bridge, while wizardless `keepBridge` behavior remains unchanged (§38: 24/24, §40: 9/9).
-- **Memory & reachability** — motivation profile / wish pool / companions / travel timeline; English output via `GOTRY_LOCALE=en`
-- **Bounded agent tool loops** — a soft convergence context is injected after real dispatch 16; dispatch 18 is the last tool body, already-prepared calls 19+ receive structured `TOOL_BUDGET_EXHAUSTED` failures without entering the body, and inherited native tool schemas are suppressed at `step/end` for a text-only next step. The boundary is exercised through the packaged `dist` entry and a real dsh headless loop against an offline relay; CI packs the current SHA and repeats the E2E from an isolated pnpm consumer install rather than the root development tree. Direct/programmatic calls are outside this per-turn budget.
+1. **The model translates; the solver decides.** The LLM never produces feasibility verdicts or arithmetic — those are computed by Z3 against the extracted facts.
+2. **Every number carries a source tag** — attached by the render layer, never the model. Tags switch honestly on degradation; an estimate never poses as realtime.
+3. **No write path exists.** Booking/payment-class tools must pass WriteGate before any implementation ships; the future booking seam is already pinned by the `booking_saga_fsm.v1` edge table.
+4. **Login never touches credentials.** Login happens on the external website; GoTry reads cookie names only; consent is asked once per session and revocable.
+5. **Retrieval is physically read-only.** A ReadGuard aborts write requests at the network layer; a captcha stops the agent and hands control back to you.
+6. **Unverifiable means blocked.** The fact gate refuses to deliver any itinerary whose bookable claims cannot trace to exact-date tool results — it is never presented as a verified plan.
+7. **Prices fail closed.** Unknown models get no guessed price; the price table changes only by PR; the drift monitor reports, never auto-applies.
+8. **Your data is yours.** Product state lives under `gotry-state/`; automated tests and smoke runs use isolated state roots and never write the founder's real product data.
 
-**Open limitations** (as of 2026-08-29, honest list):
+## Project Status
 
-- ⏳ **M3 Exit not closed** — engineering & distribution ready, but real seed-user evidence (50–200 person cohort) not yet accumulated; automated tests prove contracts and formulas, not business pass
-- ⏳ **Ctrip-hotel / Meituan logged-in adapters** — flights done; hotel session surfaces await real login-state backfill (next tick)
-- ⏳ **Interface language** — English currently covers the deterministic solve-output layer only; the dsh host UI and dialogue surface belong to the host / calibration samples
-- ⏳ **External benchmark generalization / Phase 1 bridge** — Round 1's exact DeepSeek treatment was environment-unavailable/schema-invalid (score 0), while GLM timed out at 300 s. Round 2 added the default-off owner-local bridge; its frozen treatment remained diagnostic-only because no structured native bridge call or tagged JSON reached the evaluator. Round 3 added provider-neutral native-call/result/terminal conformance, but its new frozen treatment still stopped after one runner spawn with planner/runner exit 1, zero released terminal bytes, no evaluator entry, and null official scores. Round 4's treatment at SHA `5ebddb2` had primary preflight pass, but planner/runner both exited 1 after 30.968 s, released 0 bytes, the evaluator was not entered, and official scores were null. The product Node gate was v24.20.0 while that treatment used v26.3.0, so the result remains diagnostic-only with no uplift claim. GitHub Node 22/24 §48 separately exposed a source default-off 30 s lifecycle hang. Round 5 is limited to removing the timer/keepalive preload, pinning the root/package DSH closure to alpha.3, making source checkout resolve that locked runtime before the legacy vendored fallback, preserving source normal-mode state under `ts/dsh-runtime/gotry-state/` while benchmark/package runs use the invocation directory for isolation, rejecting a non-alpha.3 benchmark runtime before spawn, enforcing Node 22.15+, and adding a benchmark-only structured diagnostic pipe with allowlisted redacted reason codes while stdout remains fail-closed. Its frozen treatment at code SHA `752e54c` stopped after 140.715 s with `child_nonzero_exit`, zero terminal bytes, and null evaluator/official scores, so it remains diagnostic-only; the lock-consistency successor does not rewrite that UID attribution. Cross-benchmark evidence remains open. See [`docs/benchmark-environment-bridge.md`](docs/benchmark-environment-bridge.md).
-- ⏳ **Round 6 structured terminal diagnostics** — benchmark mode maps only the final structured `turn/end` into closed, redacted model/runtime reason families. A per-session arbiter emits at most once and preserves a specific bridge/conformance reason over a later generic runtime reason; recovered transient retries emit no failure. Free-form messages, raw stderr, paths, prompts, request IDs, and credentials never cross the control pipe. The frozen ChinaTravel treatment at code SHA `c61600b` (`..._00001`, `deepseek-v4-flash`) stopped after 49.546 s with `child_runtime_error`, zero terminal bytes, and null evaluator/official scores; leakage and local credential/endpoint scans were zero. This is diagnostic evidence only and creates no score/uplift claim; later documentation-only successors do not rewrite the treatment attribution.
-- ⏳ **Round 7 minimal benchmark kernel** — at code SHA `edb9392896625adbb48abae4a2ecf968dbfc0349`, benchmark opt-in retains only tool budget, model override, one bridge, and isolation/conformance; product prompt variables, process guards, consent hooks, and ordinary GoTry tools are not installed, while the default path is unchanged. The CLI projects a stable task-agnostic persona and accepts only canonical `insert` and `system-prompt` root items, failing closed on missing, duplicate, quoted, reordered, flow, or noncanonical items. ChinaTravel frozen treatment UID `e20241028160248698752` (`easy`, `deepseek-v4-flash`) passed preflight without fallback, then ended after 80.463 s with runner exit 1 and zero/invalid terminal bytes; the evaluator was not entered, official score is null, and the case is not countable. The allowlisted attribution is `child_bridge_runner_failed`; no uplift or external benchmark closure is claimed. The next problem is a generic bridge-tool schema and recoverable domain-error contract.
+Current release: **v0.0.1-rc.18** (npm `latest` and `rc` both point here; registry pull-verified 2026-09-03: clean install / bin / dist entry all pass). Evaluation is at Phase 0 foundation — deterministic contracts, validators, and a cadence policy; no external benchmark scores, no spend, no uplift claims.
+
+**Working today** (full-stack regression green; every item has deterministic tests):
+
+- **Z3 solving engine** — feasibility verdicts + door-to-door whole-cost; the historical concurrency race is fixed and regression-gated
+- **Realtime retrieval** — flights/trains/hotels (Fliggy official channel), destination/hotel catalogs, weather, live flight observation, route connectivity; realtime prices can overwrite solver prices (`GOTRY_REALTIME_PRICING=1`); exhausted FlyAI anonymous trial quota is classified `needs-setup` with key guidance (no blind retries)
+- **Dependency doctor** — `npx gotry doctor` (CLI) / `gotry_doctor` (in-chat tool): read-only health check of optional dependencies (extension / Agent-Reach / hbcli / FlyAI key / sidebar / dsh-calendar mount / dsh-map-tools & dsh-tool-ask-user presence) with exact repair guidance; `--fix` installs; LLM keys stay with the dsh host
+- **Account-session search** — Ctrip flights **and hotels** + 12306 trains on your Chrome (hotels 2026-09-03: real logged-in prices via passive sniffing; trains 2026-09-03: public left-ticket query; interface surfaces calibrate with the first live session); observed runs scored every landed hit 13/13 with zero write attempts, while non-hits stay explicit `miss` records — no live-availability claim beyond that
+- **Extension install on demand** — `[GoTry Session Bridge](https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd)` is offered as a clickable link in the dsh UI when an account-session tool first needs it (one-click install + auto-update); the gotry side never runs a setup wizard
+- **Memory & reachability** — motivation profile / wish pool / companions / travel timeline; English solve output via `GOTRY_LOCALE=en`
+- **Routed turn budgets** — every turn is classified (quick / sync / deep-planning) by a deterministic, zero-LLM router; time is the only budget and the deadline exit follows the task: quick and sync turns converge to an answer, deep-planning turns hand off to a persisted background ticket (`gotry_turn_handoff.v1`, ETA ≈1h) instead of dying mid-stream; the ticket is collected in the background by `scripts/turn-handoff-collect.ts` (idempotent, recursion-guarded child planner) and surfaces in-chat via the read-only `gotry_turn_handoff_list` tool; exercised end-to-end through a packaged consumer install in CI
+
+**Open limitations** (honest list):
+
+- **M3 Exit not closed** — engineering & distribution are ready, but real seed-user evidence (50–200 person cohort) has not been accumulated; automated tests prove contracts and formulas, not business pass
+- **Hotel session adapters** — Ctrip-hotel / Meituan logged-in surfaces await real login-state backfill; flights are done
+- **Interface language** — English covers the deterministic solve-output layer; the dsh host UI and dialogue surface belong to the host / calibration samples
+- **External benchmark generalization** — every frozen external run to date remains diagnostic-only (no score, no uplift claim); the round-by-round engineering ledger lives in [`docs/evaluation/benchmark-environment-bridge.md`](docs/evaluation/benchmark-environment-bridge.md)
+- **Booking** — nothing bookable ships today; M5 opens only through WriteGate and the booking-saga FSM
 
 <details>
-<summary>📖 Deeper engineering state (ledger contracts / evidence contracts / milestone stance)</summary>
+<summary>Deeper engineering state (ledger contracts / evidence contracts / milestone stance)</summary>
 
-The authoritative state lives in the docs, not this README: transactional state ledger (ADR-15) + dual-form freeze (ADR-16: one ledger semantics for local+web); the M3 real-cohort evidence contract stands (fixtures don't count toward Exit; 50–200 real samples open the gate);
-- the M4 paired-cohort value evidence contract (run-all §34 — synthetic data is never Exit evidence);
-- async work-order terminal contract (`gotry_async_terminal.v1`: 4/4 → succeeded / ledger settled / exit 0). Details: [`docs/roadmap.md`](docs/roadmap.md) / [`docs/architecture.md`](docs/architecture.md) §1 and issues #19–#22.
+The authoritative state lives in the docs, not this README: transactional state ledger (ADR-15) + dual-form freeze (ADR-16: one ledger semantics for local+web); the M3 real-cohort evidence contract stands (fixtures don't count toward Exit; 50–200 real samples open the gate); the M4 paired-cohort value evidence contract (synthetic data is never Exit evidence); the async work-order terminal contract (`gotry_async_terminal.v1`: 4/4 → succeeded / ledger settled / exit 0). Details: [`docs/roadmap.md`](docs/roadmap.md) / [`docs/architecture.md`](docs/architecture.md) §1 and issues #19–#22.
 
 </details>
 
----
+## Roadmap
+
+| # | Milestone | Scope | Status |
+|---|---|---|---|
+| M0 | Deterministic pipeline | dual engine implementations + real data packs + reconciliation | ✅ |
+| M1 | Agent form established | LLM in the loop; chat as interface; gates as choice cards | ✅ 2026-08-22 |
+| M2 | Realtime data | hotelbyte bridge + flight sources; evidence chain switches to realtime tags | ✅ 2026-08-22 |
+| M3 | MVP | minimal web face + 50–200 seed users (Erhai / Phuket scenarios) | **← current — evidence open** |
+| M4 | Memory & "next departure" | six-layer memory C-end domain; paired-cohort value evidence | founder-authorized parallel |
+| M5 | Transaction loop | WriteGate in production; booking / payment / refunds | entry-gated |
+| M6 | B2B embedding | principal/sponsor plugin with zero kernel changes | entry-gated |
 
-## 🧪 Verify
+The single authoritative timeline — entry/exit conditions, deliverables, and gates per milestone — is [`docs/roadmap.md`](docs/roadmap.md).
+
+## Verify
 
 ```bash
-./scripts/run-all-tests.sh
-# Evaluation Phase 0 diagnostic contracts and deterministic cadence planner
-# (offline; no adapter/scheduler/runner/spend/score/Python)
+./scripts/run-all-tests.sh                     # full-stack suite (pure TS, no Python needed)
 cd ts
-npx tsx scripts/evaluation-contract-tests.ts
-npx tsx scripts/evaluation-cadence-tests.ts
+npx tsx scripts/evaluation-contract-tests.ts   # evaluation Phase 0 contracts (offline)
+npx tsx scripts/evaluation-cadence-tests.ts    # deterministic cadence policy/planner
 ```
 
-One-shot full-stack green (pure TS, no Python needed): golden engines · dialogue replay · cross-process async work-orders · plugin smoke · hbcli · process guards · weather · flights · Anything · probePoi · agent-reach · dual-path stability · time-awareness eval · memory domain · **Z3 race (§30)
-- · realtime pricing (§31) · i18n catalog (§32) · M3 cohort evidence contract (§33) · M4 value evidence contract (§34) · M3 nightly evidence producer contract (§35) · session transport extension bridge (§38) · extension onboarding pre-check (§40) · bookable-fact gate (§39)
-- · extension distribution channel (§43) · sf-live static-golden offline contracts (§44) · evaluation foundation and cadence policy (§45–§46) · agent tool-budget Cordis integration + dsh headless E2E (§47)**. The live runner remains `cd ts && npx tsx scripts/sf-live-benchmark.ts --golden=static` and requires the user's connected Chrome session.
+The suite covers golden engines, dialogue replay, cross-process async work-orders, plugin smoke, realtime bridges, process guards, i18n, memory domain, the Z3 concurrency gate, the fact gate, and a packaged-consumer turn-deadline E2E, among others; the authoritative section list is whatever `scripts/run-all-tests.sh` enumerates. The live session benchmark (`npx tsx scripts/sf-live-benchmark.ts --golden=static`) is opt-in, requires your connected Chrome session, and never runs in CI.
 
----
+## Contributing
 
-## 🤝 Contributing
+Branch off latest `main` (`feat/ · fix/ · docs/ · chore/`), full suite green locally, open a Pull Request — `main` never takes direct pushes. CI (Node 22/24, typecheck + all suites) plus maintainer review, then squash-merge. **Red tests never merge.** Full guide: [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports / feature suggestions: use the issue templates (search existing issues first).
 
-> *PR-based flow: branch off the latest `main`, full suite green, open a Pull Request — `main` never takes direct pushes. Full guide: [CONTRIBUTING.md](CONTRIBUTING.md).*
+## For AI Agents
 
-Standard open-source flow: branch off latest `main` (`feat/ · fix/ · docs/ · chore/`), full suite green locally, open a PR; CI (Node 22/24, typecheck + all suites) plus maintainer review, then squash-merge. **Red tests never merge.**
+If you are an agent working in this repository, [`AGENTS.md`](AGENTS.md) is the binding contract — read it first. In brief:
 
----
+- **Sweep async work orders on entry**: `ts/gotry-state/async/*.json` without a matching `.deliverable.md` → `cd ts && npx tsx scripts/async-collect.ts <id>`.
+- **Layer discipline**: arithmetic only in the evaluate layer of `model.ts` / `unified.py`; solving only in `unified.ts` / `unified.py`; `engine.*` / `journey.*` are deprecated compatibility layers — new code must not call them. Any side change requires the full-stack regression.
+- **Never write shared state**: `ts/dsh-runtime/gotry-state/` is the founder's real product data; validate write paths with an isolated `stateRoot` only.
+- **State-sync discipline**: any commit changing the system's shape/state/debt must sync the six state faces of `architecture.md` §11 in the same commit; stage only named files — never `git add -A`.
 
-## 📜 License
+Program-level context: [`docs/gotry-master-outline.md`](docs/gotry-master-outline.md). Technical authority: [`docs/architecture.md`](docs/architecture.md).
 
-**MIT** (2026-08-23) — same as upstream dsh. See [LICENSE](LICENSE).
+## Documentation
+
+| Document | Purpose |
+|---|---|
+| [`docs/README.md`](docs/README.md) | Docs conventions & full index (taxonomy, naming, lifecycle) |
+| [`docs/architecture.md`](docs/architecture.md) | System, ADRs, evolution, debt ledger (Chinese, authoritative) |
+| [`docs/gotry-master-outline.md`](docs/gotry-master-outline.md) | Program master outline & reuse matrix |
+| [`docs/gotry-product-design.md`](docs/gotry-product-design.md) | Product design: main loop, transparency, whole-cost model |
+| [`docs/roadmap.md`](docs/roadmap.md) | M0–M6 timeline & current position |
+| [`docs/user-guide.md`](docs/user-guide.md) | End-user guide |
+| [`docs/data-sources.md`](docs/data-sources.md) | Data sources & evidence-chain policy |
+| [`docs/ops/extension-privacy.md`](docs/ops/extension-privacy.md) | Session Bridge extension privacy |
+| [`docs/evaluation/benchmark-environment-bridge.md`](docs/evaluation/benchmark-environment-bridge.md) | External benchmark bridge — engineering ledger |
+| [`docs/evaluation/evaluation-foundation.md`](docs/evaluation/evaluation-foundation.md) | Evaluation Phase 0 foundation |
+| [`docs/design/booking-saga-fsm.md`](docs/design/booking-saga-fsm.md) | Booking saga FSM (the M5 seam vocabulary) |
+| [`docs/research/kimi-postmortem.md`](docs/research/kimi-postmortem.md) | A real AI-travel-planning failure postmortem (cautionary tale) |
+| [`docs/evaluation/persona-bench/`](docs/evaluation/persona-bench/) | Agent-persona benchmark — same real-trip prompt answered by mainstream AIs: transcripts, scoring rubric, and the persona it shapes |
+| [`docs/release-notes.md`](docs/release-notes.md) | Release decisions per version (the "why") |
+| [`CHANGELOG.md`](CHANGELOG.md) | Machine-derived changelog (Keep a Changelog + Conventional Commits) |
+| [`docs/tokens.md`](docs/tokens.md) | npm 2FA / release mechanics |
+
+## License
+
+**MIT** — same as upstream dsh. See [LICENSE](LICENSE).
 
 ---
 
-**Built with**: DeepSeek Harness 0.1.2-alpha.3 (root-pinned) · Cordis · Z3 (WASM) · loopx (pipx) · hotelbyte-cli · Agent-Reach v1.5.0 (`.venv/`) · OpenFlights · TypeScript
+**Built with**: DeepSeek Harness 0.1.2-alpha.3 (root-pinned) · Cordis · Z3 (WASM) · loopx (pipx) · hotelbyte-cli · Agent-Reach v1.5.0 · OpenFlights · TypeScript
 
-**Version baseline: `v0.0.1-rc.16` (2026-08-30).** The current checkout's authoritative verification gates are enumerated by `scripts/run-all-tests.sh` (release flow: `scripts/publish-npm.sh`).
+**Version baseline: `v0.0.1-rc.18` (npm `latest`).** The authoritative verification gates for the current checkout are enumerated by `scripts/run-all-tests.sh`; release flow: `scripts/publish-npm.sh`.