memhouse 0.20.0 → 0.20.2

package/docs/guides/install.md

@@ -128,3 +128,6 @@ The path proves nothing on its own: Homebrew's prefix is `/usr/local` on Intel a
 - `memhouse plugins install claude`: the `/mem:*` skills, for Claude Code only. Codex and the
   other editors' sessions ship all the same; an agent there reads the house with the CLI
   (`memhouse q`, `memhouse room-sql`). See [Search, resume and skills](search-and-resume.md).
+- `memhouse plugins install codex`: for Codex, a short block in its `AGENTS.md` (the rules) and
+  a `memhouse` skill (the read recipes). Nothing is written under the Codex home unless you run
+  it. See [Codex](search-and-resume.md#codex).

package/docs/guides/invite.md

@@ -27,6 +27,13 @@ memhouse invite alice --url https://house.example.com
 - **Alice installs with `memhouse install --env invite-alice.env`.** It offers to rotate
   the password to one only she knows, which works because she is granted `ALTER USER` on
   herself. Then it deletes the file. Once she rotates, the password you saw stops working.
+- **The invite expires.** The password in the file stops working 7 days after the invite
+  (`--expires <days>` sets 1 to 365), counted by the server's clock. The output, the file and
+  the invitation page say when. Installing lifts the expiry, whether she changes the password
+  or keeps it with `--keep-password`. After the date, `install` refuses the file and tells her
+  to ask for a new invite. Her account is still there, so remove it first (`DROP USER alice`, as
+  the administrator; `invite` says so when it meets it), then invite her again. Her tables are
+  kept and reused.
 
 ## Which admin credential
 

package/docs/guides/search-and-resume.md

@@ -99,6 +99,36 @@ missing skill never announces itself.
 For an agent that does not use Claude Code skills, `memhouse prompt` prints a snippet for
 its system prompt: where memory lives and how to query it.
 
+### Codex
+
+The `/mem` skills are for Claude Code. For Codex:
+
+```bash
+memhouse plugins install codex      # under CODEX_HOME, or ~/.codex
+memhouse plugins list               # shows the codex copy and the command it runs
+memhouse plugins remove codex
+```
+
+It writes two things, and only when you run it:
+
+- **A block at the top of `AGENTS.md`**, between `<!-- memhouse:begin … -->` and
+  `<!-- memhouse:end -->`. Codex puts this file in every prompt, so the block holds only what must
+  always hold: never read or print `~/.memhouse/env` or a `MEMHOUSE_*` value; `MEMHOUSE_URL` is the
+  house and `MEMHOUSE_PORT` the dashboard; questions about past sessions go to the `memhouse`
+  skill. The file is created if it is missing. Installing again replaces the block where it
+  stands. Removing takes out the block and the blank line after it, so the rest of the file is
+  what it was, byte for byte; a file that held only the block is deleted, or, when `AGENTS.md`
+  is a symlink, its target is emptied and the link kept. Leave the markers
+  alone: with one of them missing, install and remove refuse and change nothing.
+- **A skill, `skills/memhouse/`**, with the read recipes: `memhouse q`, `--member` for a
+  housemate's sessions, `memhouse room-sql`. Codex lists it by name and description and reads
+  the rest when it uses it. The directory carries `.memhouse.json`; a `skills/memhouse` without
+  it is someone else's, and install refuses to replace it and remove leaves it.
+
+For an instance with its own home or binary, both name it: `MEMHOUSE_HOME=<home> <binary> q …`.
+After an upgrade, the first `memhouse` command refreshes both, as it does the `/mem` copies; a
+block you took out by hand stays out.
+
 ## Writing your own queries
 
 On schema 3 (0.20), the tables are `mem.<you>_session_parts` (one row per part of a message:

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
@@ -106,6 +107,10 @@ included. A grant someone made by hand in SQL does not appear there. A member ca
 `system.grants` or `system.row_policies`; an administrator can, with `SHOW GRANTS FOR <user>`
 and the queries in [Operate](operate.md#who-is-here).
 
+It also lists the other direction: each member whose sessions your credential can read, with
+the command that reads them. A scoped share shows only the rows its owner chose, and its filter
+is the owner's to see.
+
 ## Reading what was shared with you
 
 Shared tables sit in the same database as yours, under the other member's name, for

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.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` |
 | [0.18.10](v0.18.10.md) | 2026-10-08 | security: the admin password never on argv; no member password printed; a scoped share reaches only its scope |

package/docs/releases/v0.20.1.md

@@ -0,0 +1,114 @@
+# memhouse 0.20.1 — 2026-11-02
+
+A patch release on 0.20.0, with no schema change. Install it with `memhouse update`, or
+`npm install -g memhouse`.
+
+- **An invite's password expires.** It stops working 7 days after the invite unless it is
+  installed first. A file that sits unused, or that was read where it should not have been,
+  stops working on its own.
+- **Codex gets memhouse on request.** `memhouse plugins install codex` adds a short rules block
+  to Codex's `AGENTS.md` and a `memhouse` skill with the read recipes. `plugins remove codex`
+  takes out exactly those.
+- **Clearer answers from the CLI:**
+  - `memhouse <command> --help` prints that command's help;
+  - a refused credential is named before anything is written;
+  - `share --list` also shows the shares you received;
+  - `members` tells a share from a member's own tables;
+  - `discover` and `update` stop reporting problems that belong to nobody.
+- **A new minor version's first run says so,** and names the release notes to read.
+
+## Read this before upgrading
+
+Nothing in the house changes, and there is no migration. Three things behave differently:
+
+- **Inviting: the password now expires.** `memhouse invite` sets the expiry on the new account
+  using the server's clock. The default is 7 days; `--expires <days>` takes 1 to 365. The
+  output, the invite file and `MEMHOUSE-INVITATION.md` all give the date. An invitee who
+  installs after that date is refused with "this invite expired at … ask whoever invited you
+  for a new one". To invite them again under the same name, remove the unused account first
+  with `DROP USER <name>`, as the administrator; their tables are kept and reused. Invites
+  made by 0.20.0 or earlier carry no expiry and keep working as before.
+- **The first command after moving to a new minor version prints one line** to stderr. It
+  names the version it replaces and the release notes. Patch releases, downgrades and fresh
+  installs print nothing.
+- **Codex is opt-in.** Nothing is written under `~/.codex` (or `CODEX_HOME`) unless you run
+  `memhouse plugins install codex`.
+
+```bash
+memhouse update        # then: memhouse status — every line a check mark
+```
+
+## Invites
+
+- **The expiry is set by the server**, as `VALID UNTIL` on the new account, so it holds no
+  matter what the file says. `install --env` also checks the date in the file and refuses
+  before contacting the server.
+- **Installing lifts it.** A password change removes the expiry, and so does
+  `--keep-password`, which keeps the invited password.
+- **`invite --print-sql`** prints the same `ALTER USER … VALID UNTIL` statement for an
+  administrator who runs the plan by hand. The date is left as a placeholder, so the
+  statement does not parse until a real date is put in.
+- **Re-inviting an unused name** used to fail with the install message, "give their
+  password". It now says the invite was never installed, gives its expiry, and names the
+  remedy.
+
+## Codex
+
+Codex puts `AGENTS.md` into every prompt and lists each skill by its name and description,
+reading the body only when the skill is used. memhouse uses both, and only when asked:
+
+- **The block** in `AGENTS.md` holds what must always apply:
+  - never read or print the env file or a `MEMHOUSE_*` value;
+  - `MEMHOUSE_URL` is the house and `MEMHOUSE_PORT` the dashboard;
+  - questions about past sessions go to the skill.
+
+  It sits between `<!-- memhouse:begin … -->` and `<!-- memhouse:end -->` markers. A reinstall
+  replaces it where it stands. Remove takes it out and leaves the rest of the file
+  byte-identical. A file that held only the block is deleted, unless it is a symlink: then its
+  target is emptied and the link kept.
+- **The skill**, `skills/memhouse/`, carries the read recipes:
+  - `memhouse q` for search, sessions, activity by hour, spend, models, tools and machines;
+  - `--member` for a housemate's shared sessions;
+  - `memhouse room-sql` for anything else.
+
+  It is memhouse's only if it holds `.memhouse.json`. A `skills/memhouse` without that file is
+  never replaced or removed.
+- **An instance with its own home or binary** is named in both, as `MEMHOUSE_HOME=<home>
+  <binary>`.
+- **After an upgrade,** the first command refreshes an installed copy, as it does the `/mem`
+  copies. A block you took out by hand stays out.
+- **The `/mem` skills are still for Claude Code.**
+
+## Smaller changes
+
+- **`memhouse <command> --help`** prints that command's entry. A command with no entry of its
+  own still gets the whole page. `memhouse q --help` lists the named queries.
+- **A refused credential is named up front.** When ClickHouse refuses the credential (code
+  516, or 194 for a missing password), `install`, `invite` and `deploy --local` stop before
+  writing anything, with "could not authenticate as '<user>' at <url>".
+- **`share --list` also lists the shares you received,** with the command that reads each
+  one. `--json` adds `received`.
+- **`members` tells a share from a member's own tables:**
+  - own tables;
+  - each member whose sessions this account reads, scoped or full;
+  - any other grant.
+
+  `--json` adds `own`, `shares` and `other`.
+- **`discover`** shows an unreachable `http://localhost:8123` as a plain line when nothing is
+  configured to use it, instead of a ✗.
+- **`update` on a machine with no member install** (an administrator's machine) skips the
+  schema heal and migration check, instead of printing the default member's authentication
+  failures.
+- **`doctor`** names the release channel when it says a release is the latest. Offline, it no
+  longer says the install is current.
+- **Dashboard:** a browser that refuses sessionStorage keeps the access token in memory for
+  that page load, instead of showing the "open it with `memhouse dashboard`" page.
+- **/mem skills:** the schema-2 raw-SQL recipe runs `memhouse room-sql <<'SQL'` directly. It
+  used to wrap the call in a shell function, so every call asked for approval.
+
+## 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.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/memhouse/codex-plugin.js

@@ -0,0 +1,194 @@
+// `memhouse plugins install codex`: what Codex reads of memhouse, and only on request.
+//
+// Codex (0.165, checked against the request it sends) puts <codex home>/AGENTS.md into every
+// prompt in full, and lists each skill under <codex home>/skills by its name and description,
+// reading the body only when the skill is used. So the rules that must hold in every session go
+// in a short block in AGENTS.md, and the read recipes in one skill, skills/memhouse.
+//
+// The block is marker-delimited. Install puts it at the top of the file, followed by one blank
+// line, or creates the file with the block alone; a reinstall replaces it where it stands. Remove
+// takes out the block and that one line, so the rest of the file is what it was, byte for byte;
+// a file left empty is deleted, unless it is a symlink: then the target is emptied through it and
+// the link stays. The skill directory carries an ownership file (OWNER_FILE): a
+// skills/memhouse without it is somebody else's and is never replaced or removed.
+//
+// Nothing here writes under the Codex home except install, remove, and the refresh of a copy
+// that install already put there (plugin-copies.js).
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SKILL = 'memhouse';
+const OWNER_FILE = '.memhouse.json';
+const BEGIN = '<!-- memhouse:begin';
+const END = '<!-- memhouse:end -->';
+const MARKERS = /^<!-- memhouse:(begin|end)\b[^\n]*$/gm;
+
+/** The Codex home: CODEX_HOME when set, else ~/.codex. */
+function codexHome(env = process.env) {
+  return env.CODEX_HOME || path.join(os.homedir(), '.codex');
+}
+const agentsFile = (cx) => path.join(cx, 'AGENTS.md');
+const skillDir = (cx) => path.join(cx, 'skills', SKILL);
+const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+/**
+ * Where the block sits in `text`: { start, end, version }, or null when there is none.
+ * Throws when the markers do not make exactly one block, so nothing is written over a file
+ * whose block was damaged by hand.
+ */
+function findBlock(text) {
+  const begins = []; const ends = [];
+  let m;
+  MARKERS.lastIndex = 0;
+  while ((m = MARKERS.exec(text))) (m[1] === 'begin' ? begins : ends).push(m.index);
+  if (!begins.length && !ends.length) return null;
+  if (begins.length !== 1 || ends.length !== 1 || ends[0] < begins[0]) {
+    throw new Error(`AGENTS.md holds ${begins.length} memhouse:begin and ${ends.length} memhouse:end markers, not one block — fix it by hand; nothing was changed`);
+  }
+  const nl = text.indexOf('\n', ends[0]);
+  const version = (/^<!-- memhouse:begin (\d+\.\d+\.\d+\S*)/.exec(text.slice(begins[0])) || [])[1] || null;
+  return { start: begins[0], end: nl === -1 ? text.length : nl + 1, version };
+}
+
+/** `text` with `block` in it: replaced where it stands, or put first with one blank line after. */
+function withBlock(text, block) {
+  const b = findBlock(text);
+  if (b) return text.slice(0, b.start) + block + text.slice(b.end);
+  return text ? `${block}\n${text}` : block;
+}
+
+/** `text` without the block, and without the blank line install put after it. */
+function withoutBlock(text) {
+  const b = findBlock(text);
+  if (!b) return text;
+  let rest = text.slice(b.end);
+  if (b.start === 0 && rest.startsWith('\n')) rest = rest.slice(1);
+  return text.slice(0, b.start) + rest;
+}
+
+/** A path for the text, with the home directory as ~. */
+function shown(p) {
+  const h = os.homedir();
+  return p === h || p.startsWith(h + path.sep) ? `~${p.slice(h.length)}` : p;
+}
+
+/** A shell word: as is when it needs no quoting, else single-quoted. */
+function shArg(s) {
+  return /^[A-Za-z0-9_@%+=:,./~-]+$/.test(s) ? s : `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+/** The `memhouse` on PATH, resolved, or null. */
+function memhouseOnPath(env = process.env) {
+  for (const d of String(env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    const f = path.join(d, 'memhouse');
+    try { fs.accessSync(f, fs.constants.X_OK); return real(f); } catch { /* not here */ }
+  }
+  return null;
+}
+
+/**
+ * How the block and the skill name the command: `memhouse` for the default instance, else with
+ * MEMHOUSE_HOME and the binary spelled out, each only where it differs from the default.
+ */
+function invocation({ home, bin, defaultHome = path.join(os.homedir(), '.memhouse'), pathBin = memhouseOnPath() }) {
+  const parts = [];
+  if (home && real(home) !== real(defaultHome)) parts.push(`MEMHOUSE_HOME=${shArg(shown(home))}`);
+  parts.push(!bin || (pathBin && real(bin) === pathBin) ? 'memhouse' : shArg(shown(bin)));
+  return parts.join(' ');
+}
+
+function render(tpl, { mh, envFile }) {
+  return tpl.replace(/\{\{MH\}\}/g, mh).replace(/\{\{ENV_FILE\}\}/g, envFile);
+}
+
+function renderBlock({ deliveryDir, version, mh, envFile }) {
+  const body = render(fs.readFileSync(path.join(deliveryDir, 'codex', 'AGENTS-BLOCK.md'), 'utf-8'), { mh, envFile }).trim();
+  return `${BEGIN} ${version} — managed by \`memhouse plugins install codex\`; \`memhouse plugins remove codex\` takes it out -->\n${body}\n${END}\n`;
+}
+
+/** The skill directory's ownership record, or null when it is not memhouse's (or absent). */
+function readOwner(dir) {
+  try {
+    const o = JSON.parse(fs.readFileSync(path.join(dir, OWNER_FILE), 'utf-8'));
+    return o && o.owner === 'memhouse' ? o : null;
+  } catch { return null; }
+}
+
+/**
+ * Write the block and the skill. Everything is checked before anything is written: a foreign
+ * skills/memhouse or a damaged block throws with the Codex home untouched.
+ * `onlyWhereInstalled`: the refresh — the block is rewritten only where it already is.
+ * @returns {{ file: string, created: boolean, block: boolean, dir: string, mh: string }}
+ */
+function install({ codexHome: cx, home, bin, version, deliveryDir, pathBin, onlyWhereInstalled = false }) {
+  const dir = skillDir(cx);
+  if (fs.existsSync(dir) && !readOwner(dir)) {
+    throw new Error(`${shown(dir)} is not memhouse's (it has no ${OWNER_FILE}) — not replacing it; move it aside and install again`);
+  }
+  const file = agentsFile(cx);
+  let text = null;
+  try { text = fs.readFileSync(file, 'utf-8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  const mh = invocation({ home, bin, ...(pathBin !== undefined ? { pathBin } : {}) });
+  const envFile = shown(path.join(home, 'env'));
+  const writeBlock = !onlyWhereInstalled || (text !== null && findBlock(text) !== null);
+  const next = writeBlock ? withBlock(text || '', renderBlock({ deliveryDir, version, mh, envFile })) : text;
+  const skill = render(fs.readFileSync(path.join(deliveryDir, 'codex', 'SKILL.md'), 'utf-8'), { mh, envFile });
+
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'SKILL.md'), skill);
+  fs.writeFileSync(path.join(dir, OWNER_FILE), `${JSON.stringify({ owner: 'memhouse', version, home, bin: bin || null }, null, 2)}\n`);
+  // In place, not a rename: an AGENTS.md that is a symlink (a dotfiles checkout) stays one.
+  if (writeBlock && next !== text) fs.writeFileSync(file, next);
+  return { file, created: text === null && writeBlock, block: writeBlock, dir, mh };
+}
+
+/**
+ * Take out the block and the skill — the skill only when it is memhouse's.
+ * @returns {{ block: boolean, fileDeleted: boolean, emptiedLink: boolean, skill: boolean, foreignSkill: string|null }}
+ */
+function remove({ codexHome: cx }) {
+  const res = { block: false, fileDeleted: false, emptiedLink: false, skill: false, foreignSkill: null };
+  const file = agentsFile(cx);
+  let text = null;
+  try { text = fs.readFileSync(file, 'utf-8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  const next = text !== null && findBlock(text) ? withoutBlock(text) : null;
+  const dir = skillDir(cx);
+  const owned = !!readOwner(dir);
+  if (!owned && fs.existsSync(dir)) res.foreignSkill = dir;
+  if (next !== null) {
+    // Only a regular file is unlinked. Unlinking a symlink (a dotfiles checkout) would leave the
+    // block in its target, so the target is written through the link instead.
+    if (next === '' && !fs.lstatSync(file).isSymbolicLink()) { fs.rmSync(file); res.fileDeleted = true; }
+    else { fs.writeFileSync(file, next); res.emptiedLink = next === ''; }
+    res.block = true;
+  }
+  if (owned) { fs.rmSync(dir, { recursive: true }); res.skill = true; }
+  return res;
+}
+
+/** What is installed: the skill's owner record (or why not), and whether the block is there. */
+function status({ codexHome: cx }) {
+  const dir = skillDir(cx);
+  const owner = readOwner(dir);
+  let block = null; let damaged = null;
+  try { block = findBlock(fs.readFileSync(agentsFile(cx), 'utf-8')); } catch (e) { if (e.code !== 'ENOENT') damaged = e.message; }
+  return { codexHome: cx, installed: !!owner, owner, foreignSkill: !owner && fs.existsSync(dir) ? dir : null, block: !!block, blockVersion: block ? block.version : null, damaged };
+}
+
+/**
+ * The copy to refresh for `version`, or null: installed, memhouse's, bound to `home`, and older.
+ */
+function staleCopy({ codexHome: cx, home, version, compareVersions }) {
+  const owner = readOwner(skillDir(cx));
+  if (!owner || !owner.home || real(owner.home) !== real(home)) return null;
+  const c = compareVersions(owner.version, version);
+  return c === -1 || c === null ? { codexHome: cx, have: owner.version || null, home: owner.home, bin: owner.bin || null } : null;
+}
+
+module.exports = {
+  SKILL, OWNER_FILE, BEGIN, END, codexHome, agentsFile, skillDir, findBlock, withBlock, withoutBlock,
+  invocation, memhouseOnPath, renderBlock, readOwner, install, remove, status, staleCopy, shown,
+};

package/memhouse/delivery/INVITATION.md.tpl

@@ -46,7 +46,7 @@ them exist because an agent broke them:
 
 ## 0. Find your credential
 
-The install needs `{{FILE}}`, the file delivered with this page. Confirm it is here first —
+{{EXPIRY}}The install needs `{{FILE}}`, the file delivered with this page. Confirm it is here first —
 run this from the directory this page is in now, and if it prints the filename you are ready:
 
 ```

package/memhouse/delivery/codex/AGENTS-BLOCK.md

@@ -0,0 +1,11 @@
+## memhouse: past agent sessions
+
+This machine's agent sessions (Codex, Claude Code and other editors) are kept in a memhouse
+house. For a question about earlier work (what was done, when, in which hours, what it cost,
+how something was fixed), use the `memhouse` skill before saying you do not know.
+
+- Never read, print or echo `{{ENV_FILE}}`, and never print a `MEMHOUSE_*` value: they hold the
+  house's password, and this conversation may be shipped into the house. `{{MH}}` reads its
+  own configuration.
+- `MEMHOUSE_URL` is the house (ClickHouse). `MEMHOUSE_PORT` is the local dashboard's port, not
+  the house's.

package/memhouse/delivery/codex/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: memhouse
+description: "Answer from past agent sessions kept in memhouse (Codex, Claude Code and other editors): what was worked on and when, which hours or days, spend and models, tools used, how something was fixed, a past session's transcript, a housemate's shared sessions. Read-only memhouse commands. Use before saying you do not know about earlier work."
+---
+
+# memhouse: read past sessions
+
+Every command here only reads. `{{MH}}` reads its own configuration: never read or print
+`{{ENV_FILE}}` or any `MEMHOUSE_*` value.
+
+Start with `{{MH}} q schema`. The recipes below are for schema 3. On 2 (a house still on the
+0.18 rooms), `{{MH}} prompt` prints the recipes for it.
+
+## Named queries
+
+`{{MH}} q <name> --json` prints one JSON object. A session is `<harness>:<session_id>`, the
+`ref` every result carries.
+
+- Sessions about a topic (every term in one message; a "quoted phrase" as written):
+  `{{MH}} q search clickhouse "authentication failed" --json`
+- Around a hit: `{{MH}} q window <ref> --at <message_id> --json`. A whole session:
+  `{{MH}} q session <ref> --json`, paged with `--cursor`.
+- Recent sessions: `{{MH}} q recent --limit 20 --since 7d --json`
+- Which hours or days: `{{MH}} q activity --by hour --grain usage --tz <IANA zone> --json`
+  counts messages and tokens by the hour they happened; `--by day`, `--by dow`, `--by day,host`.
+- Spend and models: `{{MH}} q spend --by model --since 30d --json`, `{{MH}} q models --json`
+- Tools: `{{MH}} q tools --limit 25 --json`; one tool's calls: `{{MH}} q tool <name> --json`
+- Machines: `{{MH}} q hosts --json`. What the house holds: `{{MH}} q coverage --json`
+- Filters on most names: `--harness`, `--project`, `--folder`, `--host`, `--since`, `--until`.
+  `{{MH}} q` lists every name and flag.
+
+## A housemate's sessions
+
+Add `--member <name>` to a named query to read sessions a housemate shared with you.
+`{{MH}} share --list` names who shared with you. An empty result means nothing is visible,
+not that nothing happened.
+
+## Raw SQL, when no named query fits
+
+`{{MH}} room-sql "<SELECT …>"` runs one read-only statement. The bare names `sessions`,
+`session_parts`, `session_usage` and `calls` resolve to your tables (`--member <name>` for a
+housemate's). Read them `FINAL` with `is_deleted = 0 AND removed = 0`; a session is
+`(host, harness, harness_path, session_id, incarnation)`; take totals from `sessions`, never by
+summing parts or usage.
+
+## Answering
+
+Answer from what the commands return, cite the `ref` of each session used, and say so when a
+search finds nothing. `{{MH}} resume <ref>` prints the command that reopens a session. Cost is
+derived from token counts: an unpriced model is unknown, not free.

package/memhouse/delivery/plugin/reference/HOUSE.md

@@ -20,8 +20,8 @@ memhouse q schema      # prints 3 or 2
 - **3** — the house holds harness-sessions-sql's profile tables (`sessions`, `session_parts`,
   `session_usage`, `calls`; memhouse 0.20). Read
   [Schema 3](#schema-3--harness-sessions-sqls-profile) below and use **`memhouse q`**; nothing about
-  epochs, `seq` or the `q()` rewrite applies. Skip everything from "Connect" on unless you
-  need raw SQL, and then use `memhouse room-sql`, not `q()`.
+  epochs, `seq` or the 0.18 rooms' name rewrite applies. Skip everything from "Connect" on
+  unless you need raw SQL, and then use `memhouse room-sql`.
 - **2** — the 0.18 rooms (`messages`, `tool_calls`, `sessions`). Everything from
   "What this is" on is for you, unchanged.
 
@@ -161,8 +161,8 @@ Every member's rooms are named for them — `mem.alice_messages`, `mem.alice_ses
 `mem.alice_tool_calls` — and one grant covers exactly those: `ON mem.alice_*`. Housemates
 keep their own rooms beside yours and cannot read them, list them, or grant them onward;
 you cannot read theirs. `SHOW GRANTS` shows you the one line you hold. **A bare
-`FROM messages` names nothing you have** — the `q()` below prefixes room names with your
-member name for you, and `memhouse rooms` prints what yours are called.
+`FROM messages` names nothing you have** — `memhouse room-sql` (below) prefixes room names
+with your member name for you, and `memhouse rooms` prints what yours are called.
 
 An **operator** owns the ClickHouse itself; an **admin credential** is what proves it.
 `memhouse whoami` says which you are holding.
@@ -189,13 +189,11 @@ instances on two channels; the top of this file says when to use it instead of p
 Credentials resolve **flags > exported `MEMHOUSE_*` > `$MEMHOUSE_HOME/env`** (default
 `~/.memhouse/env`), and the CLI does that itself: you never source the file, and the
 password never appears in a command. Every read goes through `memhouse room-sql`, with the
-SQL on stdin:
+SQL on stdin. Run it as written, not through a shell function: the skills pre-approve
+`memhouse room-sql`, and a wrapper would ask for approval every time.
 
 ```bash
-q() {  # read-only by construction; every read path uses this
-  memhouse room-sql "$@"
-}
-q <<'SQL'
+memhouse room-sql <<'SQL'
 SELECT 1 FORMAT PrettyCompact
 SQL
 ```

package/memhouse/delivery/plugin/skills/access/SKILL.md

@@ -116,7 +116,7 @@ each one:
 memhouse share <user>                          everything you own
 memhouse share <user> --only project=memhouse  just one project
 memhouse share <user> --only session=<id>      just one conversation
-memhouse share --list                          who can read it, and how much
+memhouse share --list                          who can read it, how much, and whose you can read
 memhouse share <user> --revoke                 withdraw
 ```