memhouse 0.18.12 → 0.20.1

package/docs/releases/v0.20.0.md

@@ -0,0 +1,627 @@
+# memhouse 0.20.0 — 2026-10-29
+
+0.20 changes how memhouse stores what it captures. It is the first release since 0.18.11;
+there is no 0.19.
+
+- **Schema 3.** A session is keyed by its store: the machine, the editor, the editor's data
+  folder (for OpenCode, its database file) and the session's own id. Each member gets six
+  conversation tables, the harness-sessions-sql profile: `<m>_session_parts`, `<m>_session_usage`,
+  `<m>_session_links`, `<m>_session_lifecycle`, `<m>_calls` and `<m>_sessions`. Each member also
+  gets a capture archive in `<db>_archive` (`<m>_session_units` and `<m>_session_sources`) that
+  keeps every transcript byte as captured.
+- **Nothing is cut or lost.** Tool output is kept in full. A message an editor reverts,
+  rewinds or deletes stays in the house as a removed version: never counted, and listed by
+  `memhouse q removed`.
+- **A fork is billed once.** Where a session copies another and the copy can be told, the copied
+  prefix counts only in the original: by the link agy and Copilot CLI state, or by a matching first
+  reply in OpenCode, VS Code, cursor-agent, Cursor and Goose. Other editors' copies, Claude
+  Code's and Codex's included, are not covered.
+- **Ten editors read as they store their sessions.** Each has a normaliser that reads its
+  store directly: agy, Copilot CLI, Cursor, cursor-agent, Devin, Gemini CLI, Goose,
+  OpenCode, VS Code and Zed. Claude Code and Codex are read natively, and the remaining
+  editors through their 0.18 readers.
+- **Moving a 0.18 house is a deliberate admin step, and `memhouse update` never does it.**
+  A 0.18 house keeps working on 0.20, unchanged, until its admin converts it.
+- **memhouse is Apache-2.0 from this release.** Releases up to 0.18.11 remain MIT.
+
+## Read this before upgrading
+
+### `memhouse update` installs 0.20 and does not convert the house
+
+A machine on 0.20 keeps shipping a 0.18 house's rooms until two things happen: the admin
+converts the member, then the machine is switched with `memhouse migrate --v3-switch`.
+Every machine can be upgraded first, days before the conversion.
+
+Behind a registry mirror, 0.18's own `update` asks registry.npmjs.org and cannot see 0.20.
+There, run `npm install -g memhouse@<version>`, then `memhouse update --no-install`.
+
+`update` still does what every update does to the rooms it ships into: it creates a missing
+room or column for the new code (`ship --ensure-schema`), and can run a pending 0.18
+migration (it asks first; `--migrate` or `--yes` say yes). It never converts to schema 3.
+
+### Converting a house is the admin's procedure
+
+[Upgrade to 0.20](../guides/upgrade-to-0.20.md) is the whole procedure. Run each step with
+`--dry-run` first; each refuses before changing anything when the house is not in the
+state it expects.
+
+1. `memhouse migrate --v3-prepare --member <m>` fences the 0.18 writers off and renames the
+   member's rooms into `<db>_archive` as `*_pre_v3`. Nothing is deleted.
+2. `memhouse migrate --v3-convert --member <m>` converts the rooms into schema 3. It takes
+   the cached tokens out of 0.18's Gemini CLI input (see Fixed), and `--dry-run` says how
+   many rows and tokens that is.
+3. `memhouse migrate --v3-reconcile --member <m>` compares the legacy and converted rows,
+   session by session.
+4. `memhouse migrate --v3-shares --member <m>` moves the member's recorded shares.
+5. `memhouse migrate --v3-switch`, on every machine, followed by a restart.
+
+The upgrade guide also gives the rollback for before any machine has switched.
+
+### A house in daily use is converted on its own schedule
+
+**Converting a house people depend on is not part of `npm update` or of this release.** It
+rewrites that house's data: the conversion, the host re-key to sessions-model/host/v0, and the
+OpenCode key. Plan it first, as its admin decides: the steps, the rollback copy, the disk it
+needs, and the downtime. Until then the house stays on the 0.18 rooms, and its machines can run
+0.20 against it unchanged.
+
+### New houses
+
+A house created by 0.20 (`deploy --local`, `install --admin-user`, `invite` into an empty
+server) is schema 3. Joining an existing house follows the layout the house already has,
+and a house with members on both layouts is refused until `--schema` says which.
+
+### Scripts that pass `--admin-password`
+
+`--admin-password <value>` is refused in 0.20 (it was deprecated in 0.18.10). A script that
+passes it stops with exit 2 and nothing done. Give the password in `MEMHOUSE_ADMIN_PASSWORD`
+or with `--admin-password-file` (a file at mode 600, or `-` for stdin) instead. See
+[the admin password guide](../guides/admin-password.md).
+
+## Security note for 0.18 houses: member names that collide
+
+**What it allows.** A member is granted its tables through one prefix wildcard: `bob` holds
+`mem.bob_*`. That prefix also matches the tables of any member whose name is `bob` plus an
+underscore and more, such as `bob_smith`. So `bob` can **read and write** `bob_smith`'s
+sessions. Mostly the longer name's tables are exposed, to the shorter name. When the longer
+name's extra part starts one of the shorter name's table names, the reverse holds too:
+`mem.bob_session_*` matches `bob`'s `bob_session_parts`. Checked on ClickHouse 26.7
+(2026-10-22). Every memhouse release up to 0.18.11 created such members without a warning, so
+an existing house may have a pair.
+
+**Check your house, as its admin:**
+
+```sql
+SELECT name FROM system.users ORDER BY name
+```
+
+Look for one name that is another's plus `_`. On a schema-3 install, `memhouse doctor` run as
+the shorter-named member names the pair too.
+
+**What 0.20 does.** It refuses to create a member whose name collides (install and invite),
+`memhouse doctor` names an existing pair, and `memhouse migrate --v3-shares` refuses to move
+shares in such a house. memhouse cannot untangle an existing pair yet. If you find one, the
+choices are in [Troubleshooting](../guides/troubleshooting.md#two-member-names-that-collide).
+Both of them touch another person's data, so decide before acting.
+
+## What changes for you
+
+### Capture
+
+- **Every row carries its store.** `host` is now sessions-model/host/v0: the first 32 hex
+  of a hash of the OS machine id, the same for every reader on the machine. Where no machine
+  id can be read, it is a random id kept on disk (`r-…`). `memhouse doctor` lists the 0.18
+  id under "host identity" as an alias of this machine.
+- **The capture archive.** `<db>_archive.<m>_session_units` holds every captured byte;
+  `<m>_session_sources` holds the cursor of each source: its generation and how far it has been
+  read. Each read writes a manifest beside its units, so an emptied or shrunk source replays correctly
+  from the archive alone. A session file the editor deletes stays in the house, recorded
+  once as gone.
+- **A session the editor deletes is recorded as gone only on the editor's own word.** On the
+  profile layout, a session or source the editor's store no longer lists is read once more, and
+  is recorded as gone (its records kept) only when the editor's reader answers that it is not
+  there. A session the list leaves out that still reads is captured as usual. In 0.20 this
+  covers the editors read through the harness-session-adapters package, Claude Code and Codex; the
+  others are read from their normalised logs, which are never swept (see Known issues), and
+  join when they move to the package. The Claude Code and Codex readers look a session up in
+  the store again, so a session whose folder is missing both when the store is listed and when
+  it is read is taken as gone; when it comes back it is read again in full, in a new
+  generation. Only a store whose list names none of the sessions the house holds of it (an
+  empty or unreadable store) is refused whole.
+  - **The shipper log says so.** After the pass line, a `vanish refused: <editor> <store>: …` line
+    names each refused store (and a session the list left out that still reads, or could not be
+    read), and `memhouse doctor` fails a line naming them until a later pass is clean. A
+    `vanish warning: …` line names a listed session's source the list left out that still reads;
+    doctor shows it and does not fail.
+  - **An emptied store needs one step.** A store whose every session was deleted lists nothing,
+    which is what an unreadable store looks like, so it is refused on every pass. If its
+    sessions were deleted, run the command the refusal names:
+    `memhouse doctor --confirm-empty-store <editor>:<store>` (the store path quoted when it has
+    spaces). It confirms the sessions the last pass refused (those recorded as gone already
+    replay without it). The next pass that finds the store there, its list still empty and no
+    other session held takes each as gone where the editor's reader says it is; a list that names
+    a session again, or a session held that it does not name, cancels the confirmation.
+  - At most 100 sessions a store are taken per pass; the rest follow on the next passes.
+- **Normalisers.** The ten editors above write a normalised session log under
+  `$MEMHOUSE_HOME/session-logs/`, and the engine captures from it. Sub-agents are child
+  records, so a log grows by appending. Reading is bounded to 30 s a pass, and a store that
+  is busy or locked fails the pass rather than reading as fewer messages.
+- **OpenCode is keyed by its database file** (`opencode.db`, `opencode-<channel>.db`, or
+  `OPENCODE_DB`), not its data folder (sessions-model §1).
+- **Converted 0.18 rows dedupe against capture.** After the switch, each captured session
+  absorbs the converted rows of the same session, so nothing is counted twice. Rows whose
+  transcripts are gone stay, counted once.
+- **A fork is billed once.** A fork that names its origin (agy, Copilot CLI) is checked against
+  it message by message, on content. Its usage that copies the origin's counts only in the
+  origin; a message the fork ran again is billed in the fork. `memhouse doctor` counts the forks
+  billed once and the links it could not verify. A fork that keeps no pointer to its origin
+  (OpenCode, VS Code, cursor-agent, Cursor, Goose) is found by its first reply: a session whose
+  first answer (at least 40 characters) is an earlier session's is checked against it the same
+  way. Two unrelated sessions whose first exchanges match word for word and token for token
+  cannot be told from a fork.
+- **An adapter upgrade re-derives each session from its archive, and its first pass takes
+  longer.** The first pass after an adapter states a new version replays each of its sessions'
+  archived passes one by one under that version (harness-sessions-sql §8):
+  - every record it makes, current or a removed version, is written again at the new version;
+  - every key it no longer makes is deleted, a removed version included, except a key the new
+    version still holds back, which stays as last written.
+
+  A session with a single archived pass is refolded instead, which gives the same rows. The
+  upgrade pass takes longer the more passes a session's archive holds. The replay reads archived
+  units at most 32 MiB and 1,000 units a response, and a pass under an unchanged version is not
+  affected. On a lab ClickHouse reached through an SSH tunnel, with a synthetic store of
+  50 sessions, the upgrade pass took:
+
+  | archived passes a session | without the re-derive (a 0.20 dev build) | 0.20 | 0.20, per 1,000 sessions |
+  |---|---|---|---|
+  | 4 | 0.6 s a session | 0.55 s | about 9 min |
+  | 12 | 0.5 s | 0.8 s | about 13 min |
+  | 24 | 0.5 s | 1.0 s | about 17 min |
+
+  The second column is a 0.20 development build's upgrade, which refolded only each session's
+  last state; at 4 passes the two are within noise. The last column scales the 50-session runs.
+  These are single runs, and round trips to the house dominate them, so read them as an order of
+  magnitude for planning, not a measurement of any real house.
+
+### Reading
+
+- `memhouse q <name>` runs named queries over schema 3: `recent`, `session`, `window`,
+  `search`, `spend`, `models`, `tools`, `activity`, `hosts`, `coverage`, `removed` and more
+  (`memhouse q --list`). A session's ref names its store (`<harness>:<id>~…`); a bare id
+  still resolves when it is unique.
+- `q window <ref>` reads around a search hit (`--at <message_id>`) or a moment (`--ts`); with
+  neither it opens at the session's first turn, so a ref from `q recent` reads as it is.
+- `memhouse status`, `doctor`, `search`, `stats` and `resume`, the dashboard and the `/mem`
+  skills read schema 3 once an install is switched.
+- The `/mem` skills install into Claude Code only. In Codex or another editor, an agent reads
+  the house with `memhouse q` and `memhouse room-sql`; `--help` and the install guide say so.
+- `MEMHOUSE_URL` is the house, its port included; `MEMHOUSE_PORT` is this machine's dashboard
+  port. `--help`, the env file and the configuration guide say so.
+
+### Importing a claude.ai export
+
+`memhouse import claude-ai <export>` stores a claude.ai data export in the house: the export's
+part zips or their folder, an older single `.zip`, an unpacked export, or an archive folder. Each
+conversation with any text becomes a `claude-ai` session with origin `import`, in one batch per
+run.
+
+- It is a dry run unless `--write`. A later export adds only the conversations the house lacks;
+  `--update` also replaces the ones that changed.
+- `--list` shows the batches and `--undo <batch> --write` tombstones one.
+- On schema 3 a conversation is a session in the service's own store, not a machine's.
+- A run that stops after all its rows went in is finished by the next `--write`. One whose
+  insert stopped early leaves its batch `applying`, and the next run writes those sessions in its
+  own batch.
+
+[Import a claude.ai export](../guides/import-claude-ai.md) has the details.
+
+### Sharing is narrower on schema 3
+
+A share, full or scoped, is `SELECT` on exactly the member's six conversation tables
+(`<m>_session_parts`, `<m>_session_usage`, `<m>_session_links`, `<m>_session_lifecycle`,
+`<m>_calls`, `<m>_sessions`), never the archive.
+
+- A scope is a row policy on each of the six. A `project=` or `folder=` scope lets no usage,
+  link or lifecycle row through (the `sessions` row carries the totals); a time scope lets no
+  link row through.
+- A full share no longer reaches `meta`, `events` or tables added later. On the 0.18 rooms
+  it was `SELECT ON <m>_*`.
+- A scope's row policies are written before any grant.
+- `source=` is `harness=` on schema 3; `source=` still works.
+
+`--v3-shares` moves the shares memhouse recorded. It refuses, changing nothing, when the
+record and the grants ClickHouse holds disagree. [Share and revoke](../guides/share.md) has
+the details.
+
+## Security
+
+- **Reading an editor's store never writes into it.** On 0.18, the SQLite readers (Cursor,
+  Goose, OpenCode, Zed, Antigravity) could create `-wal` and `-shm` files in the editor's
+  folder: a WAL database opened read-only creates them, and they stay after close. A WAL
+  store with no `-wal` is now read immutable, and a rollback-journal store (Zed's) with a
+  plain read under its lock. 0.18 machines that ran those readers may have such files left
+  in the editors' folders. They are SQLite's own, and the editor uses or replaces them.
+- **No reader reads a credential.** The usage path that read an editor's credentials is
+  gone. The cursor-agent normaliser never decodes credential-bearing steps or untyped
+  arguments, and redacts them from the stored model context too.
+- **A share cannot reach the archive.** The capture archive is granted to its member alone
+  (`SELECT, INSERT`, without grant option), so no share can hand over the raw transcripts.
+- **The share commands fail closed.** Every name that reaches a grant statement is checked
+  and quoted. `migrate --v3-shares` matches a member's tables and filters by exact name,
+  never by prefix, and stops on any read it cannot make. A scoped share needs the server to
+  prove that a row policy hides nothing from other readers. A 0.18 wildcard grant
+  (`<m>_*`) is taken back only from a reader who holds it: by `migrate --v3-shares`, or by a
+  member's revoke when no other member's name starts with theirs. A new share refuses while
+  the reader holds it, or while that cannot be read.
+- **Members no longer receive SHOW ROW POLICIES.** On a shared house that privilege let a
+  member list other members' scoped shares, including their filters. Admins of existing houses
+  run `memhouse migrate --v3-shares` (or the statement below) to remove it from existing
+  members.
+
+  ```sql
+  -- for each member <m> of the house <db>; a house still on the 0.18 rooms too
+  REVOKE SHOW ROW POLICIES ON <db>.<m>_* FROM <m>;
+  ```
+
+  Sharing does not need it: `memhouse share --list` shows a share's scope from memhouse's own
+  record. Where `--v3-shares` refuses to move a member's shares (two names that collide, a grant
+  it did not record), it prints this statement instead.
+- **Two member names that collide are refused.** See [the security note for 0.18
+  houses](#security-note-for-018-houses-member-names-that-collide) above.
+- **The `/mem` skills pre-approve reads only.** Each skill pre-approves only the read
+  commands it teaches, drawn from `memhouse q`, `search`, `resume`, `room-sql`,
+  `sessions-query`, `status`, `whoami`, `stats`, `instance`, `doctor` and `share --list`.
+  Every other command asks first, including one chained to a read.
+- **Joining always changes the invited password.** `install --env` changes it to a new one
+  only the member's machine knows, also when it runs without a terminal (as an agent runs
+  it). In a terminal it asks first. Only an explicit no, or `--keep-password`, keeps the
+  invited password, and the output then says the inviter still knows it. The invite file
+  and the invitation page now say the same, and both tell an agent not to open the file.
+- **An admin password is never taken from the command line.** `--admin-password <value>`,
+  deprecated in 0.18.10, is refused: the command stops before doing anything, exits 2, and
+  names `MEMHOUSE_ADMIN_PASSWORD` and `--admin-password-file` instead, without printing the
+  value. `--admin-password-file` refuses a file that group or other users can read or
+  write (`chmod 600` fixes it); a container's secret mounts are the exception.
+- **`setup` stores an administrator credential only on request.** Given a credential that
+  administers the server, `memhouse setup` writes nothing unless `--keep-admin` says so (a
+  terminal is asked, default no; `--yes` does not count). Such a password given as
+  `--password` is refused outright. Re-saving the credential already configured does not ask.
+- **The dashboard requires a token.** The dashboard now requires a per-user token; a loopback
+  connection alone is no longer enough. Open it with `memhouse dashboard`.
+- **The dashboard's port.** When it is in use, possibly by another account on this machine, the
+  dashboard takes the next free port up to 10 above and says which (`memhouse status` and
+  `memhouse dashboard` use it); a dashboard that cannot start is a warning from
+  `memhouse start`, not a failure.
+- **Report a security issue to security@memhouse.io.** It is the public contact while the
+  repository is private (`SECURITY.md`), and npm shows it as the package's `bugs` address.
+
+## Fixed
+
+- **One number for "sessions".** `memhouse instance` printed each table's row count beside its
+  name, which read as a second, different count of sessions: a table holds every version of a
+  session that is not merged yet. It now says rows, and that `status` and `stats` count the
+  sessions. `status`, `stats`, `q hosts` and `q machines` count the same live sessions.
+- **`memhouse update` reads the registry npm installs from.** It asked registry.npmjs.org
+  whatever npm was configured with, so behind a mirror it reported "the registry did not
+  answer" and could not update. It now reads `npm config get registry` (or
+  `npm_config_registry`), prints which registry it read and why one could not be read, and no
+  longer suggests `--channel` when the registry itself is the problem. Mirror users: a
+  registry that needs a login is still read without one; install by hand there, then
+  `memhouse update --no-install`.
+- **The package ships what a user needs, not the repository's rules.** `AGENTS.md` is now the
+  install and deploy guide for agents only. The conventions for working on memhouse (release
+  lines, the instruments, what the codebase learned the hard way) moved to `CONTRIBUTING.md`,
+  which stays in the repository. `memhouse/DESIGN.md`, `COMPETITION.md` and
+  `RESUME-AND-UPDATE.md` no longer ship. An agent reading files in an installed package found
+  repository rules there and took them for the user's.
+- **One machine is one writer after the move.** Converted rows keep a machine's 0.18 id and
+  captured ones carry the new one; the machine now records the pair in its member's meta (at
+  `--v3-switch` and each capture pass), and status, `q machines`, `q hosts` and doctor read the
+  0.18 id's rows as that machine. No row is rewritten.
+- **The `/mem` skills follow the memhouse that runs them.** Only `memhouse update` refreshed
+  them, so an upgrade with `npm install -g` (or one behind a registry mirror, where `update`
+  cannot see the registry) left the 0.18 skills teaching the 0.18 rooms on a schema-3 house.
+  The first command after an upgrade, or the shipper's restart, now replaces every copy bound
+  to that install with its own version's skills, never one bound to another install and never
+  with an older version. `memhouse doctor` names any it could not refresh.
+- **The `/mem` skills' pre-approved reads asked anyway.** The skills wrote each command with an
+  expansion in front of the verb, which no `allowed-tools` rule can match, so every read
+  prompted. They now write plain `memhouse …`, and those reads run without a prompt. They also
+  sent you to `SHOW DATABASES` for a share you received, which does not show it: a share is the
+  housemate's tables in your own database. It is found with `SHOW TABLES` (through
+  `memhouse room-sql`) and read with `memhouse q … --member <them>`.
+- `memhouse room-sql "DESCRIBE sessions"` told a member it lacked the privilege to read its own
+  columns: only a name after `FROM`/`JOIN` was resolved, so the server was asked about a table
+  that is not the member's. The table a `DESCRIBE`, `DESC`, `SHOW CREATE` or `EXISTS` names is
+  now resolved too. Another member's tables stay closed.
+- `status`, `doctor` and `stats` no longer call a house that answers "not connected" when
+  your tables are not where this install looks, and no longer print ClickHouse's
+  `UNKNOWN_TABLE` and the SQL behind it. They name the reason and the next step: the house
+  was moved to schema 3 (`memhouse migrate --v3-switch`), it was not moved yet, this install
+  holds an administrator credential with no rooms of its own, or there are no tables for you
+  in the configured house. `status --json` adds `reachable` and `rooms_problem`; `connected`
+  still means the house answered and its rooms could be read.
+- A shipper keeps what it read when it started. After `memhouse migrate --v3-switch` or an
+  upgrade under a running shipper, `status` showed its failing passes as a warning and exited 0.
+  It now calls that shipper stale, says why (the env file changed, or the package was installed,
+  after it started), repeats `memhouse stop && memhouse start`, and exits 1 while its passes
+  fail. A shipper that re-read the env file itself (it adopts a moved house and a newer
+  credential) is not called stale. `status --json` adds `shipper.stale`.
+- `memhouse instance` printed "schema 2" on a machine left on the 0.18 rooms after its house was
+  converted, as if all was well. It now asks the house what `status` asks and says the install
+  is stranded, with the fix. `memhouse q schema` with no house configured says `none` instead of
+  `2`.
+- `memhouse invite` from an admin home with no install of its own minted 0.18 rooms in a
+  schema-3 house. It now detects the house, as install does.
+- The invitation page `invite` writes beside the env file (`MEMHOUSE-INVITATION.md`) listed
+  the 0.18 rooms for every invite, and found the env file with `ls invite-*.env`, which matches
+  nothing written with `--out <dir>/<other-name>.env`. It now lists the tables the invite
+  created, by the house's layout, and names the env file the invite wrote.
+- `memhouse migrate`'s admin steps (`--v3-prepare`, `--v3-convert`, `--v3-reconcile`,
+  `--v3-shares`) now take `MEMHOUSE_ADMIN_USER` and `MEMHOUSE_ADMIN_PASSWORD` (or `--admin-user`
+  and `--admin-password-file`), like the other admin commands. From an admin home with no install
+  of its own they acted as the default `memhouse_root` with no password, and reported "could not
+  list mem's tables". `MEMHOUSE_USER` and `MEMHOUSE_PASSWORD` still work for them in this
+  release, with a note (see Deprecated); with no admin credential at all a step refuses before it
+  connects and names the missing variables. An authentication failure is named as one, in
+  `migrate`, `doctor` and `--v3-switch`: `could not authenticate as '<user>' at <url>`.
+- `memhouse deploy --local` stopped at the install on 0.20: only an admin may create the
+  member's archive tables. The superuser it has at hand now builds them.
+- The self-hosted example's nightly backup (`examples/04-self-hosted-team`) now includes
+  `<db>_archive`.
+- On schema 3, a machine with no Claude Code or Codex directory stopped every pass before the
+  other editors were read. It now ships whatever the normalisers and the bridge find.
+- Gemini CLI tokens were stored as Gemini reports them. Gemini counts cached tokens inside the
+  input and thought tokens outside the output, so the house charged cached tokens twice (in
+  `input_tokens` and again as `cache_read_tokens`) and never charged thoughts. Gemini CLI rows
+  now use the house split: input without the cached tokens, output with the thoughts. Usage
+  records carry the two flags of sessions-model §2.4 (`input_includes_cache`,
+  `output_includes_reasoning`). A machine that ran a 0.20 pre-release re-derives its Gemini CLI
+  sessions on its first pass after the update.
+- 0.18 stored Gemini CLI input with the cached tokens counted inside it, and stored the same
+  tokens again as cache reads, so they were charged twice. `--v3-convert` takes them out of
+  input (floor 0), and `--v3-reconcile` compares on the same rule. 0.18 never stored Gemini's
+  thought tokens, so converted Gemini CLI rows still leave them out: they cannot be recovered.
+- **Zed tokens counted only each turn's last request.** The Zed normaliser took each turn's
+  `request_token_usage`, which holds only the turn's last request, and ignored the thread's own
+  total, `cumulative_token_usage`; in the test stores that was about a tenth of the total. A Zed
+  session's usage is now that total, as one per-session series (sessions-model §2.4 "No
+  overlap"), and no message carries usage. The log keeps the total as increments, so it still
+  only appends as a thread grows. Each increment is dated by the thread's save that first showed
+  it (Zed keeps no time per message or per request), so a thread memhouse reads late, or a
+  pre-release's thread re-derived after the update, has its whole total so far on the day of its
+  last save, not on the day of the read. A thread whose total is empty records no usage, even
+  when per-turn values exist: they are last-request snapshots, not a total.
+- **Copilot CLI dropped usage that had no reply message.** A reply cut off by the output cap
+  leaves a `usage_record` and no `assistant.message`, and a compaction's own model call records
+  its tokens only on the compaction. Both are now usage rows of their own (keyed by the call's
+  `apiCallId`, or a short hash of it when it is VS Code's long opaque id, and
+  `compaction:<id>#1`), and so is a `usage_record` that has no `apiCallId` (keyed by its own
+  event id). A fork does not bill the ones it copied from its origin.
+- **A Zed message this reader does not know no longer shifts the ids after it.** Zed's replies
+  have no ids of their own: each is the user message's id plus its position. An unknown entry
+  was skipped, so the replies after it took its position. It is now kept in its place as a
+  notice naming its kind (never its content), and an unknown part of a message is a notice too.
+- **A Copilot CLI fork no longer claims its sibling.** A fork copies its origin's events,
+  including the origin's earlier "Forked this session into …" marker, which the fork read as a
+  fork of its own. Markers older than the session's own start are now the origin's history.
+- A machine that ran a 0.20 pre-release re-derives its Zed and Copilot CLI sessions on its first
+  passes after the update: both normalisers' `VERSION` rose, so every session the editor still
+  holds is read again, and a changed log is re-derived at a higher rev. A session the editor has
+  since deleted keeps the rows it had: the archive holds the normalised log, not the editor's
+  store.
+- `memhouse doctor` failed (exit 1) on an unpriced model alone, and told the reader to run
+  `memhouse update` even on the latest release, where update changes nothing and the gap stays.
+  An unpriced model is now a warning: doctor names `memhouse update` (and the release it would
+  install) only when a newer one exists, and otherwise says the cost stays unknown until a release
+  adds a price.
+
+## Known issues
+
+- **A session file deleted from disk before the move leaves no removed mark.** 0.18 recorded no
+  deletions and the conversion reads only rows, so such a session keeps its converted rows and
+  reads as current. A deletion after the switch is recorded when a capture sees it. See
+  [Upgrade to 0.20](../guides/upgrade-to-0.20.md#sessions-deleted-before-the-move).
+- **A capture pass that stops before it records its read, and finds the source changed when it
+  runs again, leaves the stopped read in the archive.** The archive keeps every read, and nothing
+  marks a read as finished, so the stopped read's units stay in their own generation. The
+  current state is right, and so is a refold. Only a replay from the archive alone, pass by pass,
+  which rebuilds the removed versions, shows the stopped read's records as removed versions that
+  the live passes never wrote. It waits for harness-sessions-sql to define a commit mark for a read (its
+  spec question 20).
+- **A session whose capture state is lost after its log was rewritten repeats its time-less
+  records.** memhouse dates a record that has no time of its own (every Zed message, for one)
+  when it first captures it, and keeps that date: it is part of the record's key in `turns`. If
+  the house loses the session's `files` row in `<db>_archive` and the machine loses its local
+  capture cache as well, memhouse reads the log again from the start and looks those dates up in
+  the archive by position. When the log was rewritten after it was first captured (a change to
+  its history, a rename), the positions have moved: the records get new dates and appear twice in
+  `turns`, once under each key. The session's own totals and counts are not affected, and Zed's
+  token increments, which carry the thread's own time, keep their keys.
+- **An emptied store keeps doctor failing until it is confirmed.** On the profile layout, a store
+  whose every session the editor deleted is refused on every pass (see Capture), and doctor names
+  it, until `memhouse doctor --confirm-empty-store <editor>:<store>` is run. Its records are not
+  touched meanwhile. A replay from the archive alone into a house whose store lists nothing
+  rebuilds only the sessions whose sources were all recorded gone before; the others wait for
+  that confirmation too.
+- **Deleted sessions of the normalised editors are not recorded as gone on the profile layout.**
+  The normaliser never deletes a session log, and a log missing from the list cannot be told from
+  one that cannot be read, so those stores are never swept: such a session's records stay current
+  and its archive replays its last read, which is what recording it gone (policy kept) would
+  give, without the event in the archive.
+- **A house replaced under the same name is swept late.** A machine keeps, per store, what the
+  last pass listed, and asks the house what it holds only when a session goes missing from the
+  list or the last sweep left something pending. A house restored from its archive under the same
+  name, with the machine's capture state kept, has its vanished sessions recorded only once a
+  listed session next goes missing. Removing the folder `$MEMHOUSE_HOME/state/derive-profile/stores/`
+  (this machine's per-store sweep state) makes the next pass ask. It also holds any empty-store
+  confirmation not yet used (`*.confirm.json`, `*.confirm.claimed`): removing it drops those too,
+  and an emptied store has to be confirmed again. Do not remove its parent, which also holds each
+  session's capture state and would make every session be read again in full.
+- **A replay takes at most 100 sessions a store per pass.** A replay from the archive alone of a
+  store with more sessions than its list names (sessions deleted since) rebuilds them over
+  several passes.
+- **A vanished session's edges can wait.** When a session leaves its store and the pass's
+  budget defers its edge recompute, no later pass revisits it, because it is no longer listed:
+  its edges are recomputed when its origin's rows next change. This only happens when an
+  inferred-fork harness runs out of nomination budget in that pass.
+- **Run one `memhouse import claude-ai` (import or undo) per member at a time.** They take no
+  lock. Two at once can:
+  - split a new conversation's rows between the two batches, since both write it at the same
+    `rev`. The read-back then disagrees, and undoing one batch removes part of the
+    conversation. Undo both batches and import again;
+  - record a batch's status wrong. An undo can be recorded `applied`: re-running it puts the
+    status right while any of its rows are still live, with partial counts; otherwise the batch
+    reads `applied` with no live sessions. An import still filling its sessions can be recorded
+    `applied` before it finishes: if it then stops, the next `--write` fills its rows.
+- **Profile rows written before the schema step retyped their table keep their old values.**
+  The pre-release draft of harness-sessions-sql v1 changed three column types. The schema step
+  (`memhouse ship --ensure-schema`, which `memhouse update` runs) changes the types of an
+  existing profile table. It casts the stored values to the new types; it does not work them out
+  again:
+  - `adapter_ver` keeps the number that encodes the version, now as text (`1000002001` for
+    `0.2.1`). The capture compares it as that version; a query returns `1000002001`.
+  - `child_stored` stays `true` where the link did not say, until the link is written again.
+  - `orig_sha256` keeps the old empty value (64 zero bytes) where it would now be null.
+
+  Rows written afterwards carry the version string, and a null `child_stored` where no statement
+  says. The two `<db>_archive` tables are the exception: a member cannot change their types, so
+  the capture keeps writing them in the old types, and `--ensure-schema` says so, until an admin
+  runs, for member `<m>`:
+
+  ```sql
+  ALTER TABLE <db>_archive.<m>_session_units MODIFY COLUMN adapter_ver LowCardinality(String), MODIFY COLUMN orig_sha256 Nullable(FixedString(64));
+  ALTER TABLE <db>_archive.<m>_session_units MODIFY COLUMN orig_sha256 REMOVE DEFAULT;
+  ALTER TABLE <db>_archive.<m>_session_sources MODIFY COLUMN adapter_ver LowCardinality(String);
+  ```
+
+  The first pass under an adapter's next version re-derives each of its sessions (see Capture),
+  which writes the conversation rows again with the version string and a null `child_stored`
+  where no statement says. The archived units are never rewritten, and the cursor rows it writes
+  again keep the old number until an admin runs the statements above.
+- **A session that moved to another adapter is not re-derived on a later upgrade.** A harness
+  whose sessions moved from one adapter to another (the log adapter's bridge rows, then a session
+  adapter's) leaves sessions that hold rows of both. On the new adapter's next version, such a
+  session is only refolded: its current records are written at the new version, and its removed
+  versions stay at the version that wrote them.
+
+Differences between the in-repo normalisers and the harness-session-adapters package (sessions-model
+v1.2), found by running both over the same stores. Each is retired when memhouse reads these
+editors through that package, after 0.20.
+
+- **Devin token totals exclude abandoned branches in 0.20.** The messages of a branch the user
+  reverted, and their usage, are not stored, so their tokens are not counted. The package keeps
+  them, flagged `on_active_branch: false`, and will count them.
+- Copilot CLI: reasoning effort is never read; assistant messages carry an empty `effort`,
+  though the call's usage record has `reasoningEffort`.
+- Copilot CLI: a tool result whose call is not in the session file is dropped. Gemini CLI keeps
+  such a result.
+- Copilot CLI: encrypted reasoning (`encryptedContent`, written by VS Code's Copilot engine) is
+  not kept as an opaque reasoning part.
+- VS Code: a tool call with no id of its own gets one built from the response's base id rather
+  than from the message that holds the call (sessions-model §1 rule 6). Only the call's key
+  differs.
+- OpenCode: a URL cut to `scheme://host` carries no `<redacted len=N>` marker (sessions-model
+  §4.2). Nothing leaks either way.
+- OpenCode v2: usage is read with basis `net`, where sessions-model §2.4 leaves both usage flags
+  unknown. No number changes while the reasoning count is zero.
+- Optional fields left empty: the session `mode` (Devin, VS Code, Copilot CLI); the call that
+  started a sub-agent, on the parent's side of the link (agy, cursor-agent, Gemini CLI, Zed); and
+  `source: injected` on the file a Zed mention expands into.
+
+## Deprecated
+
+- **Passwords on the command line: `--password`, `--member-password`, `--to-password`.** They
+  still work, with a warning on every run, and are refused from the next minor release. Use
+  `MEMHOUSE_PASSWORD`, `MEMHOUSE_MEMBER_PASSWORD` or `MEMHOUSE_TO_PASSWORD`, or the new
+  `--password-file`, `--member-password-file` and `--to-password-file` (a file at mode 600,
+  or `-` for stdin). See [the admin password guide](../guides/admin-password.md).
+- **`MEMHOUSE_USER` / `MEMHOUSE_PASSWORD` as the admin for `migrate --v3-*`.** They still work
+  when no admin variable is set, with a note on every run, and are not read for the admin steps
+  from the next minor release. Use `MEMHOUSE_ADMIN_USER` and `MEMHOUSE_ADMIN_PASSWORD`.
+- **The 0.18 rooms layout.** 0.20 still writes it, for houses not yet converted. Its
+  removal version is not decided yet. New features are schema 3 only.
+- **The 0.18 line:** 0.18 users who are not moving to 0.20 yet, upgrade to 0.18.12 or
+  later.
+
+## Deferred
+
+- `memhouse reset` and `relocate` on schema 3 (both refuse there).
+- Moving the editor adapters to the shared harness-skeleton package. That comes after 0.20;
+  until then the in-repo readers take bug fixes only.
+- A gentar suite for the 0.20 upgrade and the schema-3 install, and a phase-2 run on a
+  release candidate.
+- A full fresh-stack restore of example 04 on 0.20. Only the archive's part was checked.
+- Known follow-ups:
+  - an adapter upgrade re-emits rows at the same rev and relies on insertion order to win;
+  - `text_len` counts UTF-16 units, not code points;
+  - normaliser catch-alls for filesystem errors;
+  - Cursor sub-agent composer ids are still read from the session's first line.
+
+## How this release was tested
+
+- `npm test`: unit, v3 read and CLI, capture, dedupe, bridge, layout 3.2, the ten
+  normaliser suites, maintenance, no-credentials, and the sessions-model known-answer
+  vectors. CI runs it on ClickHouse 25.11 and 26.7, with the invite and
+  origin matrices and a headless e2e.
+- `misc/v3-share-matrix.sh` (repository; in CI): what full, scoped, narrowed and revoked shares reach,
+  read with each person's own credential.
+- `misc/upgrade-drill-0.20.sh` (repository), the upgrade drill (to be re-run on the release candidate; its
+  last full run predates the profile tables). It covers a 0.18.11
+  house with shares, and 0.20 install, join, fresh house and invites. It also covers grants the
+  move must refuse or leave alone: a schema-3 member's share, grants made by hand, a revoked
+  share that still holds a grant, a whole-database grant, and a colliding member name. It then
+  runs prepare, convert (including 0.18 OpenCode rows), reconcile, shares, switch and capture.
+  It ends with what each reader can see, doctor, search, `q removed`, and the known-answer
+  vectors on Linux.
+- `misc/profile-lab/run-all.js` (repository) on a lab ClickHouse 26.7.4.58: twelve suites on the profile
+  capture engine, among them crashes and re-runs, resets, holds, forks billed once, the retype
+  of an older table to harness-sessions-sql v1's types, and an adapter upgrade's re-derive
+  against a twin captured by the new version.
+- The harness-sessions-sql conformance kit (`misc/conformance/`, repository), kit v1 at harness-sessions-sql `96dcb3f`, on
+  ClickHouse: 22 pass, 2 not applicable to memhouse, and 1 fail, the crash-safe case of a
+  stopped read whose source changed before the re-run (Known issues).
+- The four examples, run on a lab host against 0.20.0-dev.15. Each README quotes that run.
+- The dev house has run the 0.20 dev builds since dev.1, capturing from
+  a maintainer's main machine.
+- **Agent drill: owed.** The 0.18.11 notes promised a drill before the next minor
+  (`drills/DRILLS.md`, repository). It has not run for 0.20 yet. It must run,
+  or be explicitly waived, before this release is tagged.
+
+## Not live-tested
+
+What 0.20 has not yet done on a real house or machine:
+
+- **Converting a real house end to end.**
+  - `--v3-prepare`, `--v3-shares` and `--v3-switch` have run only in the upgrade drill, on a
+    made-up house on a lab ClickHouse.
+  - `--v3-convert` has also run, during development, on a copy of a real member's data restored
+    from a backup.
+  - No production house has been converted yet (see [A house in daily use](#a-house-in-daily-use-is-converted-on-its-own-schedule)).
+- **Moving real shares.** `--v3-shares` has met only the drill's made-up readers and the CI
+  matrix's. No house with real readers has been moved.
+- **Upgrading a busy machine in place.** The drill upgrades a machine with two made-up Claude
+  Code sessions. A 0.18.11 machine shipping many editors has not been upgraded and switched.
+- **The normalisers on real stores outside one Mac.** They read live editor stores only on a
+  maintainer's main machine (macOS), into the dev house. On Linux they ran against fixtures, and
+  Windows is untested: CI runs on Ubuntu only.
+- **OpenCode channel databases** (`opencode-<channel>.db`, `OPENCODE_DB`): fixtures and the
+  conversion drill only. The machine that ran 0.20 has the default database alone.
+- **ClickHouse Cloud.** The examples ran on a lab ClickHouse 26.7 and the self-hosted compose
+  stack.
+- **Example 04's full restore** onto a fresh stack. Only the archive's part was checked on 0.20.
+- **The colliding-names guard on every path.** It runs in install (as admin) and invite.
+  `--print-sql` prints the statements without checking, and `deploy --local` makes its single
+  member in a new house.
+- **An agent drill** (`drills/DRILLS.md`, repository): owed, as said above.
+- **gentar**: no 0.20 suite yet, and no bench run on a release candidate.
+
+## Upgrade
+
+```bash
+memhouse update          # 0.20; the house stays on the 0.18 rooms
+memhouse status          # every line a check mark
+```
+
+Then, once the admin has converted your member: `memhouse migrate --v3-switch`, `memhouse
+stop && memhouse start`, and `memhouse doctor`.