memhouse 0.20.1 → 0.20.3

package/CHANGELOG.md

@@ -4,6 +4,98 @@ Versions before 0.8.0 were beta-only. Beta installs of 0.7.x and earlier should
 uninstall and reinstall — the 0.8.0 layout is new, and an in-place `update` +
 migration path is planned work, not a promise the old versions can cash.
 
+## 0.20.3 — 2026-11-03
+
+Release notes: [`docs/releases/v0.20.3.md`](docs/releases/v0.20.3.md). Read its "Read this
+before upgrading".
+
+- **An editor store memhouse cannot read is an error, never an editor with no sessions.** The
+  normalisers (agy, Copilot CLI, Cursor, cursor-agent, Devin, Gemini CLI, Goose, OpenCode, VS Code,
+  Zed) took any error reading a store for "not there", so a permission denial (macOS privacy on
+  `~/Library/Application Support`, for one) showed as no sessions and said nothing. Now only a path
+  that is not there (ENOENT, ENOTDIR) is no store. Any other error reading the store itself (its
+  folder, its database) stops that editor's pass with its errno, or SQLite's code. Each SQLite store
+  file is probed before it is opened, so a refused open is reported with its errno, not as SQLite's
+  "unable to open".
+  - One session's file or folder that cannot be read inside a readable store is skipped and
+    reported as that session's error; the editor's other sessions are still captured, and the
+    session is read once it can be.
+  - `memhouse status` and `memhouse doctor` name each editor whose store the last pass could not
+    read, with the error. On macOS, a denial under `~/Library` comes with the fix: Full Disk Access
+    for the app that runs memhouse.
+  - The normalised session logs of readable stores do not change.
+- **A changed snapshot opens the next generation** (harness-sessions-sql §4.1), and a pass stopped
+  after archiving one no longer archives it a second time when it runs again. No house reads a
+  snapshot source today, so no row changes.
+- **A pass stopped before its cursor write, then run again on other content, replays as a clean
+  run** (harness-sessions-sql SPEC-QUESTIONS q20). A replay from the archive, and an adapter
+  upgrade's re-derive, took the stopped read as a pass of its own, so a record the re-run no longer
+  saw (say, in a log rewritten between the two passes) was written as a removed version none of the
+  committed reads had. The re-run now writes under the stopped pass's time, and a replay folds the
+  two as one pass. Removed versions an earlier replay or re-derive wrote this way, 0.20.2's first
+  pass among them, stay until something re-derives that session.
+
+## 0.20.2 — 2026-11-03
+
+Release notes: [`docs/releases/v0.20.2.md`](docs/releases/v0.20.2.md). Read its "Read this
+before upgrading".
+
+- **Before upgrading: the first capture re-derives every session from its archive.** memhouse now
+  reads editors through `@agent-realm/harness-session-adapters` 1.1.0, whose adapters state
+  `adapter_ver` 0.3.0. A new adapter version is an upgrade (harness-sessions-sql §8, "Re-derive from
+  the archive"), so the first pass after `memhouse update` replays each session's archived passes
+  under 0.3.0 and writes its rows again above the house's revs. It reads the archive, not the
+  editors' stores, and writes every session once; on a large house that first pass takes longer
+  than a usual one. Later passes are as before. The editors memhouse reads through its own session
+  logs (every editor but Claude Code and Codex) re-derive in the same pass: their adapter,
+  `memhouse-bridge`, moves to 1.0.2 for the Cursor sub-agent links (below).
+- **The profile tables follow harness-sessions-sql v1.1: a record's native fields, and the units it
+  came from.** Five columns, added to an existing house by the schema step (`ADD COLUMN`, at the
+  end of the table; a new house has them at the specification's positions):
+  - `sessions.native` and `session_parts.message_native`, `part_native`: the fields of the
+    editor's own record that the adapter declares (a Claude Code message's `message.stop_reason`,
+    say), as canonical JSON, `''` when there are none;
+  - `sessions.units` and `session_parts.message_units`: the `(source_key, generation, unit_key)`
+    of each archived unit the record came from, so a row joins back to its raw line in
+    `<db>_archive.<m>_session_units`.
+  A row the capture wrote before 0.20.2 holds `''` and `[]` until its session is re-derived (above).
+  The legacy conversion leaves the five columns out of its `content_sha` line, as v1.1 asks, so a
+  converted session keeps its shas.
+- **A member's reading view of turns: `<m>_session_turns_view`** (harness-sessions-sql v1.1 §6,
+  `session_turns`, still a plan there). One row per turn of one session, a turn running from a
+  prompt to the next one, with its messages, tool calls, failed tool results and the models that
+  served it:
+  `SELECT * FROM <db>.<m>_session_turns_view(host = '…', harness = '…', harness_path = '…', session_id = '…', incarnation = '')`.
+  The schema step makes it (`CREATE OR REPLACE`). It runs as its reader (`SQL SECURITY INVOKER`),
+  so it shows nobody a row the tables would not, and a share does not reach it: a share is still
+  the six tables. It is not named `<m>_session_turns`, because a table ending in `_turns` reads as
+  a 0.18 member's room when memhouse looks for colliding member names.
+
+- **`memhouse room-sql` runs `SHOW ROW POLICIES` on ClickHouse 25.11.** It appended its output
+  format (`FORMAT PrettyCompact`, or `JSONEachRow` with `--json`) to the statement, and 25.11 parses
+  no FORMAT after a bare `SHOW ROW POLICIES` or `SHOW POLICIES`, so the statement failed with a
+  syntax error. The format now goes as the `default_format` setting, which applies to every
+  statement; a FORMAT the statement names itself still wins.
+- **The development layout (`<m>_turns`, `MEMHOUSE_LAYOUT=v3-dev`): an adapter upgrade writes above
+  the rows it replaces.** A new adapter version re-derived an unchanged file, from disk or from the
+  archive, at the rev the file's last pass had written, so its rows tied with the old ones and won
+  only by insertion order (listed under Deferred in 0.20.0). It now writes one rev above the
+  highest the house holds for that file, tombstones included. No derive code changed, so nothing is
+  re-derived. The profile tables were not affected.
+- **Cursor: a chat's sub-agents are captured as its links.** Cursor names a chat's sub-agents only
+  in the chat's own record (`subagentComposerIds`), never in a message, and the profile capture did
+  not read them there, so the links from a chat to its sub-agents were missing. The log adapter
+  (`memhouse-bridge` 1.0.2) now reads them as links stated on the chat, one per sub-agent. No live
+  Cursor store has shown a sub-agent yet: the tests use synthetic sessions. Each new sub-agent
+  still rewrites the chat's log; placing it in the log where it appeared waits for a live sample
+  (`docs/design/sessions-engine.md`).
+- **A session log memhouse cannot read is never rewritten into an empty one.** memhouse refuses to
+  rewrite the normalised log of a session that had messages into one with none, since an empty
+  read is far likelier a misread store than a real clear. It counted the old log's messages as 0
+  when the log was there but could not be read (a permission or disk error), which let that
+  rewrite through. Such a log now stops the session's pass with "cannot read the existing log
+  (<code>)", reported and retried like any other failed read.
+
 ## 0.20.1 — 2026-11-02
 
 Release notes: [`docs/releases/v0.20.1.md`](docs/releases/v0.20.1.md).

package/bin/memhouse.js

@@ -2303,6 +2303,12 @@ async function cmdStatus() {
       : fail ? warn(`shipper: running — ${out.shipper.via} — but ${fail}`)
       : ok(`shipper: running — ${out.shipper.via}`));
     if (stale) console.log('  restart it:  memhouse stop && memhouse start');
+    // An editor whose store the last pass could not read (a permission denial, macOS privacy): said, with
+    // the advice, never left to read as an editor with no sessions.
+    for (const e of (out.shipper.lastPass && out.shipper.lastPass.normaliseErrors) || []) {
+      console.log(warn(`${e.harness}: a read failed in the last pass (${e.code}): ${e.error}`));
+      if (e.hint) console.log(`  ${e.hint}`);
+    }
   }
   if (out.update) console.log(warn(`update available: ${out.update.target} on '${out.update.channel}' — you have ${PKG.version} — run: memhouse update`));
   console.log(out.daemons.dashboard
@@ -2737,6 +2743,9 @@ async function doctorTail(cfg, add) {
   // The last pass's vanish sweeps (passlog.js vanishChecks): a refused one fails, naming the command an
   // emptied store needs; a listed session's source its list left out that still read is a warning.
   for (const c of require(path.join(REPO_ROOT, 'memhouse', 'shipper', 'passlog')).vanishChecks(sh.lastPass)) add(c.ok, c.label, c.hint, { warn: !!c.warn });
+  // The last pass's normaliser errors (passlog.js normaliseChecks): a store, or a session in one, that
+  // could not be read fails, with the advice for a denial (macOS: Full Disk Access), never silently.
+  for (const c of require(path.join(REPO_ROOT, 'memhouse', 'shipper', 'passlog')).normaliseChecks(sh.lastPass)) add(c.ok, c.label, c.hint);
   // The dashboard is optional: the house, the capture and the /mem skills work without it. Not
   // running is said as a warning, never a failure: doctor's exit is the house's health, and a
   // reader chasing "memory looks wrong" must not be sent after a page nobody opened.
@@ -2896,14 +2905,13 @@ async function cmdRoomSql() {
     const body0 = qc().rewriteRooms(sql, { member, db: cfg.db, schema });
     qc().assertRead(body0);
     if (flags.print === true) { console.log(body0); return 0; }
-    const stripped = body0.trim().replace(/;\s*$/, '');
+    // The format travels as a setting, never appended to the statement (q-cli roomSqlRequest).
+    const req = qc().roomSqlRequest(body0, { json: JSON_OUT });
+    const text = await t.raw(req.body, { database: cfg.db, settings: req.settings });
     if (JSON_OUT) {
-      if (qc().hasFormat(stripped)) return qError(Object.assign(new Error('--json picks the format itself — drop the FORMAT clause'), { status: 400 }));
-      const text = await t.raw(`${stripped}\nFORMAT JSONEachRow`, { database: cfg.db });
       console.log(JSON.stringify(text.split('\n').filter(Boolean).map((l) => JSON.parse(l))));
       return 0;
     }
-    const text = await t.raw(qc().hasFormat(stripped) ? stripped : `${stripped}\nFORMAT PrettyCompact`, { database: cfg.db });
     process.stdout.write(text.endsWith('\n') || !text ? text : `${text}\n`);
     return 0;
   } catch (e) { return qError(e); }

package/docs/guides/share.md

@@ -26,6 +26,7 @@ Full or scoped, a share is `SELECT` on exactly your six conversation tables:
 | rows | all | those matching the scope, through a row policy on each table |
 | capture archive (`<db>_archive`) | not granted | not granted |
 | `<you>_meta`, `<you>_events` | not granted | not granted |
+| `<you>_session_turns_view` (your turns, a view) | not granted | not granted |
 | tables added later | not granted | not granted |
 
 ## Scopes

package/docs/releases/README.md

@@ -5,6 +5,8 @@ do, how to upgrade, what is deprecated and when it goes, and what was deferred.
 
 | version | date | headline |
 |---|---|---|
+| [0.20.3](v0.20.3.md) | 2026-11-03 | an editor store memhouse cannot read is an error, with the macOS Full Disk Access hint; a stopped pass replays as a clean run |
+| [0.20.2](v0.20.2.md) | 2026-11-03 | harness-sessions-sql v1.1's columns and a turns view; Cursor sub-agent links; the first capture re-derives every session |
 | [0.20.1](v0.20.1.md) | 2026-11-02 | invites expire; `memhouse plugins install codex`; per-command help and clearer CLI answers |
 | [0.20.0](v0.20.0.md) | 2026-10-29 | schema 3: a session is its store, nothing cut or lost, forks billed once, ten editors through normalisers; Apache-2.0 |
 | [0.18.11](v0.18.11.md) | 2026-10-10 | sessions with subagents stop re-shipping; security: no stored credential sent to `invite --url` |

package/docs/releases/v0.20.2.md

@@ -0,0 +1,134 @@
+# memhouse 0.20.2 — 2026-11-03
+
+A patch release on 0.20.1. The profile tables gain five columns, which the schema step adds in
+place, and the first capture after upgrading re-derives every session from its archive. Install
+it with `memhouse update`, or `npm install -g memhouse`.
+
+- **The profile tables gain harness-sessions-sql v1.1's five columns.** Each session and message
+  keeps the editor's own fields that its adapter declares, and the archived units it came from,
+  so a row joins back to its raw line. These notes claim no v1.1 conformance; the conformance
+  run's result is below.
+- **A reading view of turns:** `<m>_session_turns_view`, one row per turn of a session (v1.1's
+  `session_turns`, still a plan there).
+- **Cursor: a chat's sub-agents are captured as its links.**
+- **Fixes:**
+  - `memhouse room-sql` runs `SHOW ROW POLICIES` on ClickHouse 25.11;
+  - a session log memhouse cannot read is never rewritten into an empty one;
+  - on the development layout, an adapter upgrade writes above the rows it replaces.
+
+## Read this before upgrading
+
+- **The first capture re-derives every session from its archive.** This happens once, on the
+  first pass after `memhouse update`. It reads the archive, not the editors' stores, and writes
+  every session's rows again, so it takes longer than a usual pass; later passes are as before.
+  - Measured on a synthetic house of 2,500 sessions (2,000 Claude Code and 500 Codex; 110 MiB
+    of session files, 193,814 message parts), in a 4-core container with 6 GiB of memory, that
+    pass took 18 minutes on ClickHouse 26.7.4.58 and 27 minutes on 25.11.9.34: 1.5 and 1.3
+    times as long as capturing the same house for the first time. The shipper's memory peaked
+    at 348 MB and ClickHouse's at 58 MiB per query, and the next pass took 7 seconds.
+  - The time grows with the number of sessions, 0.43 seconds a session on 26.7 and 0.64 on
+    25.11 in that measurement: a house with four times as many sessions takes about four times
+    as long.
+  - Claude Code and Codex are read through `@agent-realm/harness-session-adapters` 1.1.0, whose
+    adapters state `adapter_ver` 0.3.0.
+  - Every other editor is read through memhouse's own session logs, whose adapter,
+    `memhouse-bridge`, moves to 1.0.2 (the Cursor links below).
+  - A new adapter version is an upgrade (harness-sessions-sql §8, "Re-derive from the
+    archive"), so each session is replayed under the new version and written above the house's
+    revs.
+- **The schema step adds five columns** to an existing house's `<m>_sessions` and
+  `<m>_session_parts`, at the end of each table (a new house has them at the specification's
+  positions). The member's own credential adds them; the archive tables do not change. A row
+  captured before 0.20.2 holds `''` and `[]` there until its session is re-derived, which the
+  first capture does.
+
+```bash
+memhouse update        # then: memhouse status — every line a check mark
+```
+
+## The profile tables: harness-sessions-sql v1.1's columns
+
+This adds the v1.1 columns and the `session_turns` view (a plan in v1.1).
+
+- `sessions.native`, `session_parts.message_native` and `part_native`: the fields of the
+  editor's own record that the adapter declares (a Claude Code message's `message.stop_reason`,
+  say), as canonical JSON, `''` when there are none.
+- `sessions.units` and `session_parts.message_units`: the `(source_key, generation, unit_key)`
+  of each archived unit the record came from, so a row joins back to its raw line in
+  `<db>_archive.<m>_session_units`.
+- The legacy conversion leaves the five columns out of its `content_sha` line, as v1.1 asks, so
+  a converted session keeps its shas.
+
+These notes claim no conformance. The harness-sessions-sql conformance kit, run against this
+release's code on ClickHouse 26.7 and 25.11 with the session adapters 1.1.0:
+
+- **Native is declared** passes.
+- **Units resolve** fails. memhouse numbers a source's first archived generation 0, where v1.1
+  numbers it 1, so each triple's generation is one lower than the specification's. Every triple
+  still names a unit of the session's own archive, so a row joins back to its raw line. memhouse
+  has numbered generations this way since 0.20.0. Aligning the two is 0.20.3 work.
+- **Crash-safe** keeps the failure 0.20.0 reported: a stopped read whose source changed before
+  the re-run.
+
+## A reading view of turns
+
+`<m>_session_turns_view` (harness-sessions-sql v1.1 §6, `session_turns`, still a plan there)
+gives one row per turn of one session, a turn running from a prompt to the next one, with its
+messages, tool calls, failed tool results and the models that served it:
+
+```sql
+SELECT * FROM <db>.<m>_session_turns_view(host = '…', harness = '…', harness_path = '…', session_id = '…', incarnation = '')
+```
+
+- The schema step makes it (`CREATE OR REPLACE`).
+- It runs as its reader (`SQL SECURITY INVOKER`), so it shows nobody a row the tables would not.
+- A share does not reach it: a share is still the six tables.
+- It is not named `<m>_session_turns`, because a table ending in `_turns` reads as a 0.18
+  member's room when memhouse looks for colliding member names.
+
+## Cursor sub-agents
+
+Cursor names a chat's sub-agents only in the chat's own record (`subagentComposerIds`), never in
+a message, and the profile capture did not read them there, so the links from a chat to its
+sub-agents were missing. `memhouse-bridge` 1.0.2 reads them as links stated on the chat, one per
+sub-agent.
+
+- No live Cursor store has shown a sub-agent yet; the tests use synthetic sessions.
+- Each new sub-agent still rewrites the chat's normalised log. Placing it where it appeared
+  waits for a live sample (Deferred).
+
+## Smaller changes
+
+- **`memhouse room-sql` runs `SHOW ROW POLICIES` on ClickHouse 25.11.** It appended its output
+  format to the statement, and 25.11 parses no FORMAT after a bare `SHOW ROW POLICIES` or `SHOW
+  POLICIES`. The format now goes as the `default_format` setting; a FORMAT the statement names
+  itself still wins.
+- **A session log memhouse cannot read is never rewritten into an empty one.** An old log that
+  was there but could not be read (a permission or disk error) counted as having no messages,
+  which let an empty read through. It now stops that session's pass with "cannot read the
+  existing log (<code>)", reported and retried.
+- **The development layout (`<m>_turns`, `MEMHOUSE_LAYOUT=v3-dev`):** an adapter upgrade writes
+  one rev above the highest the house holds for the file, instead of tying with the rows it
+  replaces. The profile tables were not affected.
+- **The site** no longer points readers at a repository-only document.
+
+## Deferred
+
+- **The normalisers' filesystem errors** (0.20.3): about thirty reads in the editor normalisers
+  take any error for "not there", so a permission denial (macOS privacy on
+  `~/Library/Application Support`, for one) shows as no sessions. 0.20.3 reports them by editor
+  and errno in `status` and `doctor`, with a Full Disk Access hint on macOS.
+- **Generation numbering** (0.20.3): a source's first archived generation is 0 where v1.1 says 1
+  (above).
+- **Cursor sub-agents as appended records.** An anchor would place each after the parent's last
+  message at or before the sub-agent's own `createdAt`; that waits for a live store to confirm
+  that a composer's and its bubbles' `createdAt` share one clock.
+- **`text_len` on the development layout** counts UTF-16 units, not code points.
+- **`memhouse reset` and `relocate` on schema 3**: 0.21, with a design note first.
+
+## Deprecated
+
+Unchanged from 0.20.0: passwords on the command line (`--password`, `--member-password`,
+`--to-password`), and `MEMHOUSE_USER` / `MEMHOUSE_PASSWORD` as the admin for `migrate --v3-*`,
+still work with a warning and are refused from the next minor release. See
+[0.20.0's Deprecated](v0.20.0.md#deprecated).

package/docs/releases/v0.20.3.md

@@ -0,0 +1,111 @@
+# memhouse 0.20.3 — 2026-11-03
+
+A patch release on 0.20.2, with no schema change and no re-derive. Install it with `memhouse update`,
+or `npm install -g memhouse`.
+
+- **An editor store memhouse cannot read is an error, never an editor with no sessions.** A
+  permission denial (macOS privacy on `~/Library/Application Support`, for one) used to show as
+  an editor with nothing in it. `memhouse status` and `memhouse doctor` now name the editor, the
+  error and, on macOS, the fix: Full Disk Access for the app that runs memhouse.
+- **A pass stopped before it finished, then run again on other content, replays as a clean run.**
+  A replay from the archive, and an adapter upgrade's re-derive, no longer write removed versions
+  for records no committed read had.
+- **A changed snapshot opens the next generation** (harness-sessions-sql §4.1).
+
+## Read this before upgrading
+
+Nothing in the house changes, and there is no migration or re-derive. Two things behave differently:
+
+- **An unreadable store is reported.** Where an editor's store could not be read, the shipper used
+  to read it as empty; now the pass reports the error for that editor and leaves its sessions as
+  they were. If `memhouse status` shows a line like
+  `cursor: a read failed in the last pass (EACCES): …`, read the hint under it. On macOS it is
+  almost always the privacy setting: give the app that runs memhouse (your terminal, or the
+  service's node) Full Disk Access in System Settings > Privacy & Security, then restart it
+  (`memhouse stop && memhouse start`).
+  - One session's file that cannot be read inside a readable store is reported as that session's
+    error; the editor's other sessions are still captured.
+- **Removed versions a replay wrote by mistake stay until that session is re-derived.** 0.20.2's
+  first pass re-derived every session, and a session whose archive held a pass stopped part way,
+  then re-run after its source changed, may hold a removed version of a record no committed read
+  had. It is never counted and shows only in `memhouse q removed`. Nothing removes it now; the next
+  re-derive of that session does.
+
+```bash
+memhouse update        # then: memhouse status — every line a check mark
+```
+
+## Editor stores memhouse cannot read
+
+The editor normalisers (agy, Copilot CLI, Cursor, cursor-agent, Devin, Gemini CLI, Goose, OpenCode,
+VS Code, Zed) took any error reading a store for "not there".
+
+- Now only a path that is not there (ENOENT, ENOTDIR) is no store. Any other error reading the
+  store itself (its folder, its database) stops that editor's pass with its errno, or SQLite's code,
+  and the editor's sessions keep their logs.
+- A refusal inside a readable store (one session's file or folder) skips that session alone and
+  reports it; it is read once it can be.
+- Each SQLite store file is opened for reading before SQLite opens it, so a refused open is reported
+  with its errno (EACCES, EPERM), not as SQLite's "unable to open database file". A SQLite error on
+  a file that opened stays an error, named by its code (`SQLITE_CANTOPEN`, `SQLITE_NOTADB`).
+- `memhouse status` prints each such error with its hint; `memhouse doctor` fails one check per
+  editor and code. On macOS, a denial under `~/Library` comes with the Full Disk Access hint.
+- The normalised session logs of readable stores do not change.
+
+## A stopped pass, then other content
+
+A pass that stops between its archive write and its cursor write (the shipper killed, a ClickHouse
+error part way through a session) is run again by the next pass. When the editor's store changed in
+between, so that something the stopped pass read is gone, the live state was always right, but a
+replay from the archive treated the stopped read as a pass of its own and wrote what it read as a
+removed version.
+
+- The re-run now writes under the stopped pass's time, and a replay folds the two as one pass, as a
+  clean run of what was committed would (harness-sessions-sql SPEC-QUESTIONS q20).
+- A pass stopped after it wrote its rows has already shown what it read; live keeps any of it the
+  re-run no longer sees as a removed version, which a replay does not make. An adapter upgrade's
+  re-derive removes it.
+
+## Conformance
+
+These notes claim no conformance. The harness-sessions-sql conformance kit v1.1.1 (harness-sessions-sql
+4c7c330), with the session adapters 1.1.0 (harness-skeleton e1e5900), ran against memhouse at 1c6ffbc,
+this release's code (the release commit adds only the version and these notes), on ClickHouse
+26.7.4.58 and 25.11.9.34, with the same result on both. The kit passed every item that applies to
+memhouse: 25 pass.
+
+- **Crash-safe** passes, the crash followed by other content included (0.20.2's one open fail).
+- **Units resolve** passes: 1,170 triples, the broad scenario's 1,060 and a kept vanish's 55 live and
+  55 replayed.
+- **Units only**, **Native is declared** and **Absences replay** (reset and gone keys; vanished, kept)
+  pass.
+- Two **Absences replay** parts are not applicable: memhouse declares only the `kept` vanish policy, so
+  "vanished, removed" and "policy changed" do not apply.
+- **Database profile parity** was not run: memhouse has a ClickHouse profile only.
+
+## Smaller changes
+
+- **A changed snapshot opens the next generation** (harness-sessions-sql §4.1), and a pass stopped
+  after archiving one no longer archives it twice when it runs again. No house reads a snapshot
+  source today (Claude Code, Codex and memhouse's own session logs are streams), so no row changes.
+- **Generation numbering:** no change. harness-sessions-sql v1.1.1 (sessions v1.4.4) makes only the
+  order of a source's generations significant, so memhouse's archives, whose first generation is 0,
+  conform as they are.
+- **The test suites of the capture engine run in CI** on both ClickHouse lines (repository).
+
+## Deferred
+
+- **Cursor sub-agents as appended records.** An anchor would place each after the parent's last
+  message at or before the sub-agent's own `createdAt`; that waits for a live store to confirm
+  that a composer's and its bubbles' `createdAt` share one clock.
+- **`text_len` on the development layout** counts UTF-16 units, not code points.
+- **The capture's per-session rollup query** costs a fixed 0.2 to 0.4 seconds a session; 0.21, with
+  a design note first.
+- **`memhouse reset` and `relocate` on schema 3**: 0.21, with a design note first.
+
+## Deprecated
+
+Unchanged from 0.20.0: passwords on the command line (`--password`, `--member-password`,
+`--to-password`), and `MEMHOUSE_USER` / `MEMHOUSE_PASSWORD` as the admin for `migrate --v3-*`,
+still work with a warning and are refused from the next minor release. See
+[0.20.0's Deprecated](v0.20.0.md#deprecated).

package/editors/normalise/agy.js

@@ -67,6 +67,7 @@
 //   table or column throws. The runner retries a failed session.
 
 const fs = require('fs');
+const fsx = require('./fsx');
 const path = require('path');
 const crypto = require('crypto');
 const { placeChildren } = require('../sessions-log');
@@ -377,10 +378,12 @@ function spillRef(uri, shown, stepsDir, sid) {
   if (!m || m[1] !== sid) return null;
   const file = path.join(stepsDir, m[2], 'output.txt');
   let st;
-  try { st = fs.statSync(file); } catch { return null; }
+  st = fsx.stat(file);
+  if (!st) return null;
   if (!st.isFile() || st.size <= Buffer.byteLength(String(shown || ''), 'utf-8')) return null;
   let buf;
-  try { buf = fs.readFileSync(file); } catch { return null; }
+  buf = fsx.readBytes(file);
+  if (!buf) return null;
   return buf.length > Buffer.byteLength(String(shown || ''), 'utf-8') ? { sha: sha256(buf), len: buf.length } : null;
 }
 
@@ -803,8 +806,8 @@ function fromTranscript(sid, text, summary, ann) {
 // The one error that may read as empty: a table or column an older schema lacks. Everything else
 // (busy, locked, SQLITE_PROTOCOL, malformed, IOERR, NOTADB) fails list() or normalise().
 const isMissing = (e) => /no such (table|column)/i.test(String((e && e.message) || e));
-function readdir(dir) { try { return fs.readdirSync(dir); } catch { return []; } }
-function isFile(p) { try { return fs.statSync(p).isFile(); } catch { return false; } }
+function readdir(dir) { return fsx.readdir(dir) || []; }
+function isFile(p) { return fsx.isFile(p); }
 
 function readSummaries(file) {
   const out = new Map();
@@ -831,30 +834,33 @@ function readSummaries(file) {
  * conversation_summaries.db is not named: what is read from it is in the entry.
  */
 function list(storeRoot = storeRootDefault()) {
-  if (!fs.existsSync(storeRoot)) return [];
+  if (!fsx.stat(storeRoot)) return [];
   const harnessPath = require('../harness-paths').resolveNative(storeRoot);   // = dataFolder('agy') for the default store
   const byId = new Map();
   const add = (id) => {
     if (!byId.has(id)) byId.set(id, { harness: HARNESS, session_id: id, harness_path: harnessPath, root: storeRoot, db_path: null, wal_path: null, transcript_path: null, annotation_path: null, summary: null });
     return byId.get(id);
   };
+  const errors = [];   // a session whose file could not be read: skipped, reported (fsx.entry)
   const conv = path.join(storeRoot, 'conversations');
   for (const f of readdir(conv)) {
     const m = /^(.+)\.db$/.exec(f);
-    if (m && isFile(path.join(conv, f))) { const e = add(m[1]); e.db_path = path.join(conv, f); e.wal_path = `${e.db_path}-wal`; }
+    if (m && fsx.entry(errors, m[1], () => isFile(path.join(conv, f)), false)) { const e = add(m[1]); e.db_path = path.join(conv, f); e.wal_path = `${e.db_path}-wal`; }
   }
   const brain = path.join(storeRoot, 'brain');
   for (const id of readdir(brain)) {
     const p = path.join(brain, id, '.system_generated', 'logs', 'transcript_full.jsonl');
-    if (isFile(p)) add(id).transcript_path = p;
+    if (fsx.entry(errors, id, () => isFile(p), false)) add(id).transcript_path = p;
   }
   const sums = readSummaries(path.join(storeRoot, 'conversation_summaries.db'));
-  for (const e of byId.values()) {
+  for (const e of [...byId.values()]) {
     e.summary = sums.get(e.session_id) || null;
     const ann = path.join(storeRoot, 'annotations', `${e.session_id}.pbtxt`);
-    if (isFile(ann)) e.annotation_path = ann;
+    const has = fsx.entry(errors, e.session_id, () => isFile(ann), null);
+    if (has === null) { byId.delete(e.session_id); continue; }   // its annotation refused: the session waits, reported
+    if (has) e.annotation_path = ann;
   }
-  return [...byId.values()].sort((a, b) => (a.session_id < b.session_id ? -1 : a.session_id > b.session_id ? 1 : 0));
+  return fsx.listed([...byId.values()].sort((a, b) => (a.session_id < b.session_id ? -1 : a.session_id > b.session_id ? 1 : 0)), errors);
 }
 
 function dbSource(db, transcript) {

package/editors/normalise/copilot-cli.js

@@ -45,6 +45,7 @@
 //   not conversation: they are left out of the log.
 
 const fs = require('fs');
+const fsx = require('./fsx');
 const path = require('path');
 const crypto = require('crypto');
 const harnessPaths = require('../harness-paths');
@@ -63,16 +64,17 @@ function list(storeRoot = storeRootDefault()) {
   const base = path.join(storeRoot, 'session-state');
   // The data folder's real path: absolute, symlinks resolved, in the filesystem's own case.
   const harnessPath = harnessPaths.resolveNative(storeRoot);
-  let names = [];
-  try { names = fs.readdirSync(base); } catch { return []; }
+  const names = fsx.readdir(base);
+  if (!names) return [];
   const out = [];
+  const errors = [];   // a session whose file could not be read: skipped, reported (fsx.entry)
   for (const sid of names) {
     const dir = path.join(base, sid);
     const events = path.join(dir, 'events.jsonl');
-    try { if (!fs.statSync(events).isFile()) continue; } catch { continue; }
+    if (!fsx.entry(errors, sid, () => fsx.isFile(events), false)) continue;
     out.push({ harness: HARNESS, harness_path: harnessPath, session_id: sid, dir, events, workspace: path.join(dir, 'workspace.yaml') });
   }
-  return out;
+  return fsx.listed(out, errors);
 }
 
 /** Complete lines only: a partial last line is held back. */
@@ -139,8 +141,7 @@ function normalise(session) {
     : parseEvents(fs.readFileSync(session.events, 'utf-8'));
   let ws = session.workspace;
   if (!ws || typeof ws === 'string') {
-    let txt = '';
-    try { txt = fs.readFileSync(ws || '', 'utf-8'); } catch { txt = ''; }
+    const txt = (ws && fsx.readText(ws)) || '';
     ws = parseWorkspace(txt);
   }
   const start = events.find((e) => e.type === 'session.start');

package/editors/normalise/cursor-agent.js

@@ -78,6 +78,7 @@
 //   A referenced blob that is missing means a torn read: normalise returns null and the pass skips.
 
 const fs = require('fs');
+const fsx = require('./fsx');
 const path = require('path');
 const crypto = require('crypto');
 const { fileURLToPath } = require('url');
@@ -99,7 +100,7 @@ function storeRootDefault() { return harnessPaths.dataFolder(HARNESS); }
 
 const md5 = (s) => crypto.createHash('md5').update(s).digest('hex');
 const sha256 = (b) => crypto.createHash('sha256').update(b).digest('hex');
-function sortedDir(dir) { try { return fs.readdirSync(dir).sort(); } catch { return []; } }
+function sortedDir(dir) { return (fsx.readdir(dir) || []).sort(); }
 
 /**
  * Sessions in one store: every chats/<bucket>/<chatId>/ and acp-sessions/<id>/ that has a store.db.
@@ -109,19 +110,20 @@ function sortedDir(dir) { try { return fs.readdirSync(dir).sort(); } catch { ret
  * not named: it is rewritten (updatedAtMs) on every open, and only its cwd is read, as a fallback.
  */
 function list(storeRoot = storeRootDefault()) {
-  try { if (!fs.statSync(storeRoot).isDirectory()) return []; } catch { return []; }
+  if (!fsx.isDir(storeRoot)) return [];
   const harnessPath = harnessPaths.resolveNative(storeRoot);
   const out = [];
+  const errors = [];   // a chat whose folder or store could not be read: skipped, reported (fsx.entry)
   const add = (dir, sid, bucket) => {
     const db = path.join(dir, 'store.db');
-    try { if (!fs.statSync(db).isFile()) return; } catch { return; }   // empty or refused-headless chat
+    if (!fsx.entry(errors, sid, () => fsx.isFile(db), false)) return;   // empty or refused-headless chat
     out.push({ harness: HARNESS, harness_path: harnessPath, session_id: sid, dir, db, wal: `${db}-wal`, bucket });
   };
   const chats = path.join(storeRoot, 'chats');
-  for (const b of sortedDir(chats)) for (const id of sortedDir(path.join(chats, b))) add(path.join(chats, b, id), id, b);
+  for (const b of sortedDir(chats)) for (const id of fsx.entry(errors, b, () => sortedDir(path.join(chats, b)), [])) add(path.join(chats, b, id), id, b);
   const acp = path.join(storeRoot, 'acp-sessions');
   for (const id of sortedDir(acp)) add(path.join(acp, id), id, null);
-  return out;
+  return fsx.listed(out, errors);
 }
 
 // ── protobuf wire format: just enough to walk the store ───────────────────────────────────────
@@ -468,7 +470,9 @@ function parseMetaValue(v) {
   } catch { return null; }
 }
 function readMetaJsonCwd(dir) {
-  try { const j = JSON.parse(fs.readFileSync(path.join(dir, 'meta.json'), 'utf-8')); return typeof j.cwd === 'string' ? j.cwd : ''; } catch { return ''; }
+  const text = fsx.readText(path.join(dir, 'meta.json'));
+  if (text === null) return '';
+  try { const j = JSON.parse(text); return typeof j.cwd === 'string' ? j.cwd : ''; } catch { return ''; }
 }
 function uriPath(u) {
   if (!u) return '';
@@ -490,7 +494,9 @@ function normalise(session) {
     return build(session, pickMeta(session.meta), (id) => m.get(id), scan);
   }
   let db;
-  try { db = openReadOnly(session.db); } catch { return null; }
+  // Gone since the list: no read this pass. Any other open error (a permission denial, a file SQLite
+  // cannot open) is reported, never taken for an empty chat.
+  try { db = openReadOnly(session.db); } catch (e) { if (fsx.absent(e)) return null; throw e; }
   try {
     db.exec('BEGIN');
     const row = db.prepare("SELECT value FROM meta WHERE key = '0'").get();

package/editors/normalise/cursor.js

@@ -48,6 +48,7 @@
 //   `encrypted_model`. ItemTable is never queried at all (it holds the login rows).
 
 const fs = require('fs');
+const fsx = require('./fsx');
 const path = require('path');
 const { openReadOnly, textOf } = require('../sqlite');
 const harnessPaths = require('../harness-paths');
@@ -165,7 +166,7 @@ const bubbleRange = (cid) => [`bubbleId:${cid}:`, `bubbleId:${cid};`];
  */
 function list(storeRoot = storeRootDefault()) {
   const file = dbPathOf(storeRoot);
-  if (!fs.existsSync(file)) return [];
+  if (!fsx.stat(file)) return [];
   const harnessPath = fs.realpathSync.native(storeRoot);
   const db = openReadOnly(file);
   try {

package/editors/normalise/devin.js

@@ -80,6 +80,7 @@
 //   index. Only a missing table or column reads as empty.
 
 const fs = require('fs');
+const fsx = require('./fsx');
 const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
@@ -126,7 +127,7 @@ const isMissing = (e) => /no such (table|column)/i.test(String((e && e.message)
 function list(storeRoot = storeRootDefault()) {
   const harnessPath = harnessPaths.resolveNative(storeRoot);
   const file = path.join(harnessPath, DB_FILE);
-  try { if (!fs.statSync(file).isFile()) return []; } catch { return []; }   // no store
+  if (!fsx.isFile(file)) return [];   // no store
   // A store that is busy or locked mid-save must not read as "no sessions": an open or a query that
   // fails throws, and the runner keeps its index. Only a missing table or column reads as empty.
   const db = openReadOnly(file);