1688-cli 0.1.40 → 0.1.42

package/AGENTS.md

@@ -1,318 +1,112 @@
-# 1688 — 1688 CLI for agents
-
-When the user asks anything about 1688 sourcing, products, orders, or
-logistics, use the `1688` CLI. It outputs JSON automatically when stdout
-is piped, so `1688 <cmd> | jq` works.
-
-## Current commands
-
-Organized by buyer journey: sourcing → inquiry → cart → checkout → tracking → post-sale.
-
-```
-# Sourcing
-1688 search <keyword>                       Keyword search; --max N to limit.
-1688 search --headed                        Open window once if a slider verification appears.
-1688 similar <offerId>                      "找同款" — similar offers from other suppliers, sorted by price.
-1688 image-search <pathOrUrl>               Search by image (local .jpg/.png/.webp file or http(s) URL).
-1688 offer <offerId>                        Full product detail: title, priceTiers, SKUs, attributes,
-                                            packageInfo, supplier (loginId/memberId/province/city).
-
-# Pre-sale inquiry (seller IM, scoped by offerId)
-1688 seller inquire <offerId> <message>     Send product link + question to the supplier.
-1688 seller messages --offer <offerId>      Read replies in this offer's conversation.
-1688 seller messages --offer <offerId> --watch [--interval N]
-                                            Live-tail new replies (line-delimited JSON when piped).
-                                            Long-running; min interval 10 s, default 30 s.
-
-# Cart
-1688 cart list                              List items in 1688 cart (采购车).
-1688 cart add <offerId> --sku <skuId> --qty N
-                                            Add SKU to cart (~6 s, mtop hijack). Returns
-                                            {added: CartItem, isNewRow, addedQuantity}.
-1688 cart remove <cartId>                   Remove one cart row (~12 s, UI replay).
-
-# Checkout
-1688 checkout prepare <cartId>...           Preview total/address/items (NO order placement).
-1688 checkout confirm <cartId>...           PLACE order — TTY+prompt by default.
-1688 checkout confirm <cartId>... --agent   Agent mode: no prompt; use only after explicit approval.
-                                            MUST be preceded by `prepare` shown to the user AND
-                                            explicit user authorization in the current turn.
-
-# Order tracking
-1688 order list                             List buyer orders; --status, --page, --page-size flags.
-                                            Each order has actions[] (buyer ops + URLs), services[]
-                                            (insurance/refund), badges[].
-1688 order list --status waitbuyerreceive   Filter to "awaiting delivery".
-1688 order get <orderId>                    One order by ID (--max-scan-pages N, --status hint).
-1688 order logistics <orderId>              Tracking number + trace (mailNo, carrier, remark).
-1688 shipped <orderId>                      Order detail + logistics merged into one call.
-1688 stuck [--days N]                       Paid but not shipped > N days (default 3).
-1688 fake-shipped [--days N] [--debug]      Marked shipped but courier never collected (虚假发货).
-1688 seller-history <sellerName>            All orders from a seller + avg ship days + on-time rate.
-
-# Post-sale chat (seller IM, scoped by orderId)
-1688 seller chat <orderId|loginId> <message>
-                                            Send to seller. With orderId, auto-attaches the order card.
-1688 seller chat <orderId> <message> --no-card
-                                            Follow-up reply, no card.
-1688 seller messages <orderId>              Read replies in this order's conversation.
-1688 seller messages <orderId> --watch      Live-tail (same as the --offer form above).
-
-# Account & daemon
-1688 login                                  Show QR code; user scans with phone.
-1688 login --headed                         Use a real browser window instead (fallback).
-1688 login --force                          Re-login even if a session exists.
-1688 logout [--yes]                         Log out (prompts unless --yes).
-1688 whoami [--verify]                      Print current account; exit 3 if not logged in.
-1688 doctor [--no-launch]                   Diagnose environment + session state.
-1688 daemon start | stop | status | reload  Manage the background daemon.
-1688 serve                                  Run the daemon in the foreground.
-```
-
-## Daemon (recommended for agent use)
-
-When the daemon is running, commands route through it and share a single
-Chromium context. Benefits:
-- ~2-3 seconds saved per command (no Chrome cold start)
-- One continuous logged-in session across commands
-- Built-in inter-command jitter (1.2-3 s)
-
-The agent should call `1688 daemon start` once at the beginning of a session
-that involves multiple 1688 commands. The daemon auto-stops after 30 minutes
-of inactivity. Run `1688 daemon reload` after the package updates to pick up
-new code.
-
-`login`, `logout`, `doctor` stay inline; they need interactive UI or browser
-windows. If the daemon is running and you need to `login --force`, stop the
-daemon first.
-
-## Watch mode (long-running streams)
-
-`1688 seller messages ... --watch` is a long-running command. It:
-- Prints `Baseline: <conversation> — N messages in history` to stderr on start
-- Emits one line of JSON to stdout per **newly-arrived** message (history is
-  not re-emitted)
-- Dedup is by server-side `messageId`
-- Default interval 30 s, minimum 10 s, override with `--interval <seconds>`
-- Exits cleanly on SIGINT (Ctrl+C)
-
-For agent loops, pipe stdout into a `while read line` and parse each line as
-its own JSON object. Do not assume the process will exit — it is meant to
-stay alive.
-
-## Exit codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 2 | Bad invocation (missing flag, etc.) |
-| 3 | Not logged in / session expired |
-| 5 | Another 1688 command is running (lock busy) |
-| 6 | Chromium not installed |
-| 7 | Login wait timeout |
-| 4 | Aliyun risk control (slider verification) — retry with `--headed` |
-| 8 | Login finished but cookies missing |
-| 9 | Network error |
-| 130 | User canceled |
-
-## Status filter values (for `order list --status`)
-
-| value | meaning |
-|---|---|
-| `all` | All orders |
-| `waitbuyerpay` | 待付款 |
-| `waitsellersend` | 待发货 |
-| `waitbuyerreceive` | 待收货 |
-| `success` | 已完成 |
-| `cancel` | 已取消 |
-
-## Rules for the agent
-
-- `1688 login` opens a window the user must interact with. Only run it
-  yourself if the user explicitly asks you to log in.
-- `1688 logout` requires `--yes` in non-interactive mode. Do not pass
-  `--yes` without explicit user confirmation in the current turn.
-- If a command returns exit 3, tell the user to run `1688 login`.
-  Do not loop or retry on your own.
-- If a command returns exit 4 (risk control), tell the user to run the
-  same command once with `--headed` (they will need to drag a slider).
-  Do not retry the same command silently.
-- **`1688 checkout confirm` requires a TTY by default**, OR `--agent` flag.
-  It places real orders (no payment yet, but commits to seller). 
-  
-  **Agent protocol for placing orders:**
-  1. Run `1688 checkout prepare <cartIds>` first
-  2. SHOW the user the full preview (total, items, address, seller)
-  3. WAIT for the user's explicit "yes, place it" / "下单吧" in the current turn
-  4. Only then run `1688 checkout confirm <cartIds> --agent`
-  5. Report the final orderId / URL back to the user
-  
-  NEVER run `--agent` without the prepare+approval cycle. NEVER infer authorization
-  from older messages — it must be explicit in the CURRENT turn.
-- JSON output of `whoami`:
-  ```json
-  {"loggedIn": true, "memberId": "...", "nick": "...", "lastVerifiedAt": "..."}
-  {"loggedIn": false}
-  ```
-
-## Key JSON shapes
-
-### `seller messages` result
-
-```ts
-{
-  conversation: string,
-  total: number,
-  messages: Array<{
-    sender: string,
-    time: string | null,            // "YYYY-MM-DD HH:MM:SS" in +08:00
-    isMine: boolean,
-    content: string,
-    read: boolean,
-    kind: "text" | "offerCard" | "orderCard" | "autoReply"
-        | "assessment" | "image" | "other",
-    card?: { title: string|null, price: string|null,
-             image: string|null, url: string|null },
-    messageId?: string,             // present when sourced from WS
-  }>,
-}
-```
-
-`--watch` mode emits per-message instead:
-```ts
-{ conversation: string, message: <one item from messages[] above> }
-```
-
-### `cart add` result
-
-```ts
-{
-  ok: boolean,
-  added: CartItem,                  // see `cart list` JSON for full shape
-  isNewRow: boolean,                // true=new cartId, false=merged into existing row
-  addedQuantity: number,            // delta this call added (== args.quantity for new row)
-}
-```
-
-To get the cartId reliably in a pipeline:
-```bash
-id=$(1688 cart add <offerId> --sku <skuId> --qty 1 | jq -r '.added.cartId')
-```
-
-## Output flags (every command)
-
-In addition to `BB1688_JSON=1`, every command accepts:
-
-```
---json            Force JSON output even in a TTY.
---pretty          Indent JSON by 2 spaces.
---get <path>      Print one field by dot-path. Scalar → raw line,
-                  object/array → JSON. Wildcards stream one element per line.
-                  Syntax: field.sub, arr[N].field, arr[*].field
---pick <paths>    Comma-separated dot-paths → emit a JSON object with each
-                  path as a key. Useful for trimming output for downstream agents.
-```
-
-Examples:
-```bash
-1688 offer X --get supplier.name              # 深圳... (raw)
-1688 offer X --get supplier                   # {"name":"...","loginId":"..."}
-1688 offer X --get 'skus[*].price'            # 49 \n 68 \n 98.75 ...
-1688 offer X --pick price,supplier.name       # {"price":1.25,"supplier.name":"..."}
-1688 offer X --json --pretty                  # full payload, indented
-```
-
-When `--get`/`--pick` is given, the human renderer is skipped; the resolved
-value(s) go to stdout. The full payload still flows through when neither
-flag is set, so existing `| jq` pipelines keep working.
-
-## Login in non-interactive sessions (Codex / Claude Code / scripted)
-
-`1688 login` displays a QR code on stderr. ASCII rendering only works on
-a real TTY — when invoked from an agent, stderr is usually piped and the
-ASCII art either does not render or appears garbled.
-
-The login command always **also** saves the QR as a PNG to
-`~/.1688/login-qr.png` (`%USERPROFILE%\.1688\login-qr.png` on Windows)
-and writes `QR saved as PNG: <path>` on stderr. The agent should:
-
-1. Watch stderr for the `QR saved as PNG:` line.
-2. Surface that file to the user (display the image inline, or tell the
-   user the exact path so they can open it).
-3. Wait for the command to exit naturally — the user must scan the QR
-   with their 1688 mobile app within the timeout (default 300 s).
-
-Do not attempt to "open" the raw QR URL in a browser — it is a token URL
-that only the 1688 app can consume, not a human-readable page.
-
-## Feedback / bug reports
-
-```
-1688 feedback "<message>"            Open a pre-filled GitHub issue (TTY browser).
-1688 feedback --bug "<details>"      Tag the issue as a bug.
-1688 feedback --no-open "<msg>"      Just print the URL — useful for agents to
-                                     show the user without opening a browser
-                                     on the agent's machine.
-1688 feedback "<msg>" --submit       Post the issue DIRECTLY via the `gh` CLI
-                                     (requires `gh auth login`). Skips the
-                                     "Submit new issue" click in the browser.
-```
-
-**Agent rule for `--submit`**: do NOT add `--submit` on the agent's own
-initiative. Always run without `--submit` first, show the user the
-generated URL, and only re-run with `--submit` if the user explicitly
-asks ("submit it" / "直接发吧" / "post the issue"). Posting an issue is
-a public write action.
-
-The CLI auto-attaches anonymized environment info (version, Node, OS) and
-the last error from `daemon.log` if present. Nothing about the user's
-1688 account is sent. The actual submission still requires the user to
-click "Submit new issue" in the browser — the CLI only prepares the URL.
-
-## Update awareness
-
-At the start of a session that runs multiple 1688 commands, run
-`1688 doctor`. Its JSON output includes a `version` block:
-
-```json
-{
-  "version": {
-    "current": "0.1.27",
-    "latest":  "0.1.29",
-    "updateAvailable": true,
-    "updateCommand":   "npm i -g 1688-cli@latest",
-    "error": null
-  }
-}
-```
-
-You can also detect updates from any command: in JSON mode (piped / `--json`
-/ `BB1688_JSON=1`), a single line of structured JSON appears on stderr
-when a newer version is cached:
-
-```
-{"_notice":"updateAvailable","current":"0.1.27","latest":"0.1.29","updateCommand":"npm i -g 1688-cli@latest"}
-```
-
-### Rules for upgrades
-
-- **Interactive session** (TTY, the user is watching the conversation):
-  ask the user once whether to upgrade now. Show the current → latest
-  versions and the install command. If the user agrees, run
-  `updateCommand`, then `1688 daemon reload` to pick up the new code.
-
-- **Non-interactive** (CI, cron, scripted agent loop with no human in
-  the loop): do NOT upgrade on your own. Log the notice to stderr and
-  continue. Pinning is intentional in those contexts.
-
-- Never run the install command without explicit user authorization in
-  the CURRENT turn. The CLI version is part of the user's global
-  environment; treat it the same way you treat any `sudo` or
-  "modify global state" action.
-
-- Ask at most once per session. If the user declines or postpones,
-  don't ask again in the same session.
-
-## Discovery
-
-Run `1688 --help` and `1688 <command> --help` for the latest flags.
+# Agent Map
+
+This file is the short entry point for coding agents. Treat it as a map, not
+as the full manual. Load deeper context from `ARCHITECTURE.md` and `docs/`
+only when the task needs it.
+
+## First Read
+
+- Agent working principles: `docs/AGENT_WORKING_PRINCIPLES.md`
+- System architecture: `ARCHITECTURE.md`
+- Documentation map: `docs/README.md`
+- Default workflow: `docs/WORKFLOW.md`
+- Command catalog: `docs/COMMANDS.md`
+- JSON contracts: `docs/JSON_CONTRACTS.md`
+- Safety and approval rules: `docs/SAFETY.md`
+- Reliability and browser/session behavior: `docs/RELIABILITY.md`
+- Quality score and known gaps: `docs/QUALITY_SCORE.md`
+
+## Project Shape
+
+- `src/cli.ts`: Commander CLI surface and command routing.
+- `src/commands`: command executors and human renderers.
+- `src/session`: Playwright browser/session helpers, mtop capture, locators,
+  recovery, lock, state, and artifacts.
+- `src/daemon`: background daemon client/server/protocol/throttle.
+- `src/io`: JSON/text output, prompts, and structured errors.
+- `src/auth`: login/session verification and cookie helpers.
+- `src/util`: small shared utilities.
+- `tests`: deterministic Vitest coverage and fixtures.
+- `scripts`: probes, postinstall, and agent-map utilities.
+- `docs`: canonical agent-readable knowledge base.
+
+## Common Commands
+
+- Install deps: `pnpm install`
+- Typecheck: `pnpm typecheck`
+- Deterministic tests: `pnpm test:unit`
+- Full test run, including live doctor checks: `pnpm test`
+- Build CLI: `pnpm build`
+- Generate agent indexes: `pnpm agent-context`
+- Check generated indexes: `pnpm docs-check`
+- Check map structure: `pnpm agent-map-check`
+- Default agent gate: `pnpm agent-verify`
+
+`pnpm agent-verify` is the default green gate. If it fails, report the exact
+failure instead of hiding it.
+
+## Task Routing
+
+- New or changed CLI command: read `docs/playbooks/add-command.md`,
+  `docs/COMMANDS.md`, and the relevant `src/commands/*` file.
+- JSON output change: read `docs/playbooks/change-json-output.md` and
+  `docs/JSON_CONTRACTS.md`; preserve compatibility unless the user approved a
+  breaking change.
+- Browser risk-control / slider / login issue: read
+  `docs/playbooks/debug-risk-control.md`, `docs/SAFETY.md`, and
+  `docs/RELIABILITY.md`.
+- New mtop or response capture: read `docs/playbooks/add-mtop-capture.md` and
+  existing helpers in `src/session/*capture*.ts`.
+- Release/update behavior: read `docs/playbooks/update-cli-release.md`.
+- Sourcing research features: read `docs/specs/sourcing-research.md`
+  and `docs/FEATURES.md`.
+- Supplier search/research work: read `docs/specs/supplier-search.md`.
+- Seller IM work: read `docs/specs/seller-im.md`.
+- Checkout/order work: read `docs/specs/checkout-and-orders.md` and
+  `docs/SAFETY.md`.
+- Complex feature/refactor: create or update an ExecPlan under
+  `docs/exec-plans/active/`.
+
+## 1688 Runtime Rules
+
+- For 1688 sourcing, products, orders, or logistics, use the `1688` CLI.
+- It outputs JSON automatically when stdout is piped, so
+  `1688 <cmd> | jq` works.
+- At the start of a multi-command 1688 session, run
+  `1688 doctor --no-launch --json` and start the daemon when useful with
+  `1688 daemon start`.
+- If a command returns exit `3`, tell the user to run `1688 login`; do not
+  retry in a loop.
+- If a command returns exit `4`, tell the user to run the same command once
+  with `--headed` and solve the slider manually; do not silently retry.
+- `1688 login` opens a user-interactive QR/browser flow. Run it only when the
+  user explicitly asks to log in.
+- `1688 logout --yes` requires explicit current-turn confirmation.
+- Seller messages `--watch` is long-running and emits one JSON object per new
+  message.
+
+## Write-Action Boundaries
+
+These commands contact sellers, modify buyer state, or place orders. Use the
+protocols in `docs/SAFETY.md`.
+
+- `1688 seller inquire <offerId> <message>`
+- `1688 seller chat <orderId|loginId> <message>`
+- `1688 cart add <offerId> --sku <skuId> --qty N`
+- `1688 cart remove <cartId>`
+- `1688 checkout confirm <cartIds...>`
+- `1688 feedback "<message>" --submit`
+- `1688 logout --yes`
+
+Hard rule: never run `1688 checkout confirm ... --agent` unless
+`1688 checkout prepare <cartIds...>` was shown to the user and the user gave
+explicit current-turn approval to place the order.
+
+## Done Criteria
+
+- Relevant docs/playbooks/specs were read and updated if behavior changed.
+- `pnpm agent-context` was run after command, JSON contract, source layout, or
+  test layout changes.
+- `pnpm agent-verify` was run, or the exact blocker is recorded.
+- For complex work, active ExecPlans contain progress, decisions, and latest
+  verification.

package/ARCHITECTURE.md

@@ -0,0 +1,106 @@
+# Architecture
+
+`1688-cli` is a TypeScript command-line tool for Alibaba 1688 buyer workflows:
+sourcing, seller IM, cart, checkout, order tracking, and logistics follow-up.
+It uses Playwright with a persistent browser profile, a daemon for warm
+sessions, and stable JSON output for agents.
+
+## Layer Map
+
+```text
+src/cli.ts
+  -> src/commands
+  -> src/session
+  -> src/daemon
+  -> src/io
+  -> src/auth
+  -> src/util
+tests -> src/*
+docs/generated -> scripts/generate_agent_context.mjs
+```
+
+## Layer Responsibilities
+
+`src/cli.ts` owns the public command surface: command names, options,
+arguments, and lazy imports.
+
+`src/commands` owns user-visible behavior for each command. A command usually
+contains:
+
+- option parsing / validation
+- `execute(ctx, args)` for daemon-dispatched work
+- `run(opts)` for CLI invocation
+- human rendering through `emit({ human, data })`
+
+`src/session` owns browser automation primitives: Playwright context setup,
+mtop/response capture, locators, recovery, locking, page-state detection,
+navigation guards, artifacts, and timing helpers.
+
+`src/daemon` owns the long-lived background process, request protocol,
+client/server dispatch, and inter-command throttling.
+
+`src/io` owns output compatibility, JSON flags, prompts, and structured
+`CliError` behavior.
+
+`src/auth` owns login/session verification and cookie handling.
+
+`src/util` owns small shared helpers.
+
+`tests` owns deterministic Vitest coverage. Live/browser flows should be
+guarded or documented when they cannot be deterministic.
+
+`docs` owns durable agent-readable knowledge. `docs/generated/*` is generated
+by `scripts/generate_agent_context.mjs`.
+
+## Dependency Rules
+
+- CLI routing may import commands lazily, but command modules should not import
+  `src/cli.ts`.
+- Command modules may use `src/session`, `src/daemon/dispatch` indirectly,
+  `src/io`, `src/auth`, and `src/util`.
+- `src/session` should not depend on command modules, except shared types only
+  when there is no cleaner local session type.
+- `src/io` should stay browser-free and command-agnostic.
+- `src/daemon` should depend on command executors through explicit dispatch
+  wiring, not dynamic ad-hoc imports from arbitrary modules.
+- JSON-facing result interfaces should live near the owning command and be
+  documented in `docs/JSON_CONTRACTS.md` when stable for agents.
+
+## Major Domains
+
+- Sourcing: `search`, `similar`, `image-search`, `offer`.
+- Pre-sale seller IM: `seller inquire`, `seller messages --offer`.
+- Cart: `cart list`, `cart add`, `cart remove`.
+- Checkout: `checkout prepare`, `checkout confirm`.
+- Order tracking: `order list`, `order get`, `order logistics`, `shipped`,
+  `stuck`, `fake-shipped`, `seller-history`.
+- Post-sale seller IM: `seller chat`, `seller messages <orderId|loginId>`.
+- Account/session: `login`, `logout`, `whoami`, `doctor`, `daemon`, `serve`.
+
+## Browser And Session Model
+
+- The tool uses a persistent browser profile under `~/.1688`.
+- The daemon reuses one browser context and adds jitter between commands.
+- Commands should handle login redirects, risk-control pages, and browser
+  closure through structured exit codes.
+- `--headed` is the manual escape hatch for slider verification.
+- Browser probes under `scripts/probe-*.mjs` are exploratory tools, not stable
+  verification gates.
+
+## Generated Context
+
+- Run `pnpm agent-context` after changing commands, source layout, tests, or
+  exported JSON result interfaces.
+- Generated files live under `docs/generated`.
+- Do not hand-edit generated files; change
+  `scripts/generate_agent_context.mjs` instead.
+
+## Verification Surfaces
+
+- Type safety: `pnpm typecheck`
+- Deterministic tests: `pnpm test:unit`
+- Full test suite including live doctor checks: `pnpm test`
+- Agent indexes: `pnpm agent-context`
+- Generated docs freshness: `pnpm docs-check`
+- Agent map structure: `pnpm agent-map-check`
+- Default gate: `pnpm agent-verify`

package/CHANGELOG.md

@@ -3,6 +3,113 @@
 All notable changes to this project are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.1.41] - 2026-05-16
+
+### Added
+- **`1688 inbox` now decodes 1688 IM card messages.** What previously
+  rendered as `kind: 'other'` / `preview: '[非文本消息]'` is now broken
+  out into structured fields. The decoder reads two parallel sources
+  (`content.custom.data` base64-JSON and
+  `message.extension.dynamic_msg_content` template JSON), picks the
+  best preview text across `productTitle` / `refundTitle` /
+  `offerSubTitle` / `title` / `summary`, and emits:
+  - `lastMessage.kind` — now `'text' | 'image' | 'card' | 'archived' | 'other'`
+  - `lastMessage.cardTemplate` — semantic name when known
+    (`'order_followup'`, `'refund'`, `'offer'`, `'order_payment_reminder'`,
+    `'address_changed'`, `'evaluation_invite'`, `'coupon'`,
+    `'session_ended'`, etc.)
+  - `lastMessage.cardCode` — raw 6-digit template code (`170002`, `467001`,
+    …) so agents can filter on unmapped templates too
+  - `lastMessage.extras` — `{orderId, offerId, refundId, imgUrl, linkUrl,
+    amount}`, populated only when at least one field resolved (keeps
+    JSON output compact)
+  - New `'archived'` kind marks conversations where the server stripped
+    `content` entirely (observed on all messages > ~12 months old —
+    not a parser failure, just a server retention boundary).
+
+  Decoder is a pure function in `src/session/im-cards.ts` so it's
+  reusable from future commands and easily testable. Live-validated on
+  a 2430-conversation account: 421 of 444 cards (95%) get a meaningful
+  preview; remaining 23 cards fall back to `'[卡片消息]'` placeholder
+  with `cardCode` still surfaced. Tests in `tests/im-cards.test.ts`
+  (14 new) and `tests/inbox.test.ts` (updated).
+
+- **Opt-in JSON v2 response envelope** (`--envelope v2` / `BB1688_JSON_ENVELOPE=v2`).
+  Wraps command output in `{ok, code, data, error, meta}` with a stable
+  `meta.requestId` so agents can correlate output with the event log
+  (see below) and debug bundles. Default JSON shape is unchanged —
+  existing callers keep working bit-for-bit. Implemented in `src/io/output.ts`
+  with coverage in `tests/output.test.ts`.
+
+- **`1688 profile list` / `1688 profile status`.** A minimal profile
+  inventory backed by `~/.1688/profiles/`. `list` enumerates known
+  profiles with login state and last-used hints; `status <name>` reports
+  state file health, lock holder (if any), and the last few command
+  events for that profile. New config loader + validation in
+  `src/session/config.ts`; commands in `src/commands/profile.ts`. Tests:
+  `tests/config.test.ts`, `tests/profile.test.ts`.
+
+- **`1688 doctor --live`.** Extends `1688 doctor` with read-only live
+  checks: daemon reachability, event-log writability, artifact directory
+  writability, and recent risk-control signals from `~/.1688/runs/`.
+  Pure observation — no browser is started, no profile is touched.
+  `src/commands/doctor.ts`, `tests/doctor-live.test.ts`.
+
+- **`1688 debug list / last / show`.** Read-only post-mortem surface for
+  the command event log. `list` paginates recent commands;
+  `last` jumps to the most recent run; `show <requestId>` prints the
+  start/success/error records plus pointers into the matching
+  `~/.1688/runs/<requestId>/` artifact bundle. Powered by the new event
+  system (see below). `src/commands/debug.ts`, `tests/debug.test.ts`.
+
+- **Command request event log** (`~/.1688/events/`). Dispatched commands
+  now record `start`, `success`, and `error` events scoped to a
+  per-invocation `requestId`. Captured stdout/stderr aren't modified —
+  events are written out-of-band so existing JSON output stays
+  bit-for-bit identical. Drives `debug`, `profile status`, and
+  `doctor --live`. `src/session/events.ts`, `src/session/dispatch.ts`,
+  `src/daemon/client.ts`; `tests/events.test.ts`.
+
+- **Navigation-guard classifier (`src/session/navigation-guard.ts`).**
+  Tags unexpected page destinations encountered mid-command — login,
+  risk-control / verification, payment, or off-host external — so
+  commands can decide whether to retry, prompt, or fail with a
+  classified diagnostic instead of a raw selector-timeout. Currently
+  available as a helper; downstream commands will adopt it
+  incrementally. `tests/navigation-guard.test.ts`.
+
+### Changed
+- **`cart-add` / `cart-list` response capture scoped to its triggering
+  action.** Listeners are now armed immediately before the action that
+  causes the mtop response and disposed in `finally`, so capture
+  lifetimes track navigation/click boundaries. Ambiguous add-to-cart
+  confirmations now surface capture diagnostics (which event arrived,
+  which didn't) instead of generic timeouts.
+
+- **`search` capture lifecycle refactor.** Search / image-search /
+  similar listeners are now armed immediately before the triggering
+  action (initial navigation OR pagination click) and torn down in
+  `finally`. Page-close events surface `browser_closed` immediately
+  instead of waiting for polling timeouts. Capture also records timing,
+  final status, and parser failures so failures produce structured
+  diagnostics. Same offer dedup / pagination behavior as 0.1.40 —
+  purely a lifecycle and observability change
+  (`src/session/search-capture.ts`, `src/commands/search.ts`,
+  `image-search.ts`, `similar.ts`).
+
+- **Shared deadline-aware polling helper.** The deadline loop in
+  `src/session/wait.ts` now backs search capture's blocking waits
+  (previously had its own ad-hoc remaining-time math). Behavior
+  unchanged, but timeout handling is consistent and unit-tested in one
+  place (`tests/wait.test.ts`).
+
+### Tests
+- **Replay fixtures for offline parser coverage.** Sanitized
+  `getOfferList` mtop captures, cart `addcargo` success/failure
+  responses, and a risk-control page-state HTML now back
+  `tests/replay-fixtures.test.ts`. Parser and navigation classification
+  changes won't silently drift even if no live env is available.
+
 ## [0.1.40] - 2026-05-15
 
 ### Added