From d802dd3654948c6b95bf18ba3d633841e874cb20 Mon Sep 17 00:00:00 2001
From: omartelo <meopedevts@proton.me>
Date: Mon, 10 Aug 2026 10:08:42 -0300
Subject: [PATCH] test: assert hook payloads against lich's contract fixtures
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two sides of every hook live in different repositories: lich owns the
endpoints, this repository owns the scripts that build the payloads. A renamed
field went red in neither. lich now publishes each contract as bytes
(docs/hooks/fixtures/*.jsonl there, one case per line: the payloads it accepts
and the ones it refuses) and asserts its endpoints against them; this is the
other half.

node --test tests/*.test.mjs runs every hook script as a real subprocess — the
command line taken from the registration each harness actually reads, quoting
included — against a stub HTTP server, and asserts the body it POSTs: its key
set and value classes match some accept case, it matches no reject case, it
lands on the right endpoint with the right ?token=, and it never sends the
deprecated claude_session_id. The accepted states and providers are derived
from the fixtures rather than copied beside them, so a value lich stops
accepting stops being accepted here. A reject case with no client-side rule
fails its own test, so a contract that grows a refusal cannot slip through
unmodelled.

The client rules are pinned too: no report without the full lich environment,
and exit 0 with an empty stdout when lich answers 500 or refuses the
connection. Silence is load-bearing on Codex, where a hook's own exit code
answers a PermissionRequest.

The suite found one payload that disagreed. report-title.sh checked that it had
extracted something before posting, which a title of nothing but spaces passes,
and lich rejects a blank title with a 400. Codex made it reachable: it names a
thread after its first user message, so a prompt whose first line is
indentation produced exactly that payload. The title is trimmed before the
check now, which also matches what lich stores.

The fixtures are vendored in tests/fixtures/ so the suite never needs the
network — network in a test is flake, drift is not. tests/refresh-fixtures.sh
re-pulls them and CI diffs the copies against lich on every run, so a contract
that moves upstream goes red here without any test reaching out.
---
 .github/workflows/ci.yml             |  31 ++
 CHANGELOG.md                         |  26 ++
 CLAUDE.md                            |  24 ++
 README.md                            |   9 +
 hooks/report-title.sh                |   4 +
 tests/fixtures/session-start.jsonl   |   9 +
 tests/fixtures/session-state.jsonl   |  10 +
 tests/fixtures/session-title.jsonl   |   7 +
 tests/fixtures/session-touched.jsonl |   5 +
 tests/hooks.test.mjs                 | 595 +++++++++++++++++++++++++++
 tests/refresh-fixtures.sh            |  19 +
 11 files changed, 739 insertions(+)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 tests/fixtures/session-start.jsonl
 create mode 100644 tests/fixtures/session-state.jsonl
 create mode 100644 tests/fixtures/session-title.jsonl
 create mode 100644 tests/fixtures/session-touched.jsonl
 create mode 100644 tests/hooks.test.mjs
 create mode 100755 tests/refresh-fixtures.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..d2aa777
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,31 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: hook contract tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: node --test tests/*.test.mjs
+
+  fixtures-drift:
+    name: fixtures match lich
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Refresh from omartelo/lich@main
+        run: tests/refresh-fixtures.sh
+      - name: Fail if the vendored copies drifted
+        run: |
+          git diff --exit-code -- tests/fixtures || {
+            echo "::error::A hook contract moved in lich. Run tests/refresh-fixtures.sh, then make the scripts match."
+            exit 1
+          }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index db4f0ab..56b28f0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **The hook payloads are asserted against lich's contract fixtures.** lich
+  publishes every hook contract as bytes (`docs/hooks/fixtures/*.jsonl` there,
+  one case per line: the payloads it accepts and the ones it refuses) and
+  asserts its endpoints against them. This repository now asserts the other
+  half: `node --test tests/*.test.mjs` runs every hook script as a real
+  subprocess — from the command line its registration actually spells, for both
+  harnesses — against a stub HTTP server, and checks the body it POSTs matches
+  an accepted shape, matches no rejected one, lands on the right endpoint with
+  the right `?token=`, and never sends the deprecated `claude_session_id`. It
+  also pins the client rules: no report without the full lich environment, exit
+  0 and silence when lich answers 500 or refuses the connection. The fixtures
+  are vendored (`tests/fixtures/`, refreshed by `tests/refresh-fixtures.sh`) so
+  the suite never needs the network, and CI diffs the copies against lich on
+  every run. A field that moves in either repository now goes red in both.
+
+### Fixed
+
+- **A blank session title is no longer reported.** `report-title.sh` checked
+  that it had extracted *something* before posting, which a title of nothing but
+  spaces passes — and lich rejects a blank title with a 400. Codex made it
+  reachable: it names a thread after its first user message, so a prompt whose
+  first line is indentation produced exactly that payload. The title is trimmed
+  before the check now, which also matches what lich stores.
+
 ## [0.6.0] - 2026-08-09
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index cfa46e0..d752c65 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,6 +14,7 @@ hooks/codex-hooks.json            # hook registration, Codex
 hooks/                            # hook scripts ($CLAUDE_PLUGIN_ROOT/hooks/<script>, both)
 docs/                             # lich ⇄ plugin communication contracts
 skills/                           # skills (skills/<name>/SKILL.md, both)
+tests/                            # hook payloads asserted against lich's fixtures
 ```
 
 ## Contracts
@@ -31,8 +32,31 @@ Each doc carries the event mapping for **every** provider, one column each — a
 
 - [skills/theme](skills/theme/SKILL.md) — writing, porting and validating lich color themes, as a single file or as a versioned theme repository. Mirrors the theme contract in the lich repository (`docs/themes.md` there); `template.json` is a copy of the starter lich itself hands out, and `validate.mjs` derives its token sets from that copy. A change to the theme shape, or to the repository contract, lands here too.
 
+## Tests
+
+```bash
+node --test tests/*.test.mjs
+```
+
+[tests/hooks.test.mjs](tests/hooks.test.mjs) drives every hook script as a real
+subprocess — the command line taken from the registration each harness reads —
+against a stub HTTP server, and asserts the body it POSTs against lich's
+contract fixtures: an accepted shape, no rejected one, the right endpoint and
+`?token=`, no deprecated `claude_session_id`, plus the client rules (no lich
+environment → no report, exit 0 on a 500 or a refused connection). Node only,
+no dependencies.
+
+The fixtures are vendored in `tests/fixtures/` from lich
+(`docs/hooks/fixtures/*.jsonl` there) by
+[tests/refresh-fixtures.sh](tests/refresh-fixtures.sh), so the suite never needs
+the network; CI diffs the copies against upstream and fails on drift.
+
 ## Rules
 
+- **The fixtures are upstream truth — never edit one to get a green run.** A
+  payload that disagrees with a fixture is a bug in the script, or a contract
+  change that lands in lich first (prose, then fixtures, then its endpoint, then
+  here).
 - A hook must never block or fail the user's turn: short timeout, errors swallowed, always exit 0. On Codex the exit code is louder still — `2` on `PermissionRequest` denies the request, so silence and exit 0 are what keep a report an observation.
 - Outside lich (env vars absent) every hook is a no-op with exit 0 — the plugin must be safe to install globally.
 - A skill must be useful from any working directory: the user runs the agent CLI on their own project, not on the lich checkout.
diff --git a/README.md b/README.md
index 10f6420..13c85ea 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,7 @@ hooks/report-title.sh             # session-title hook
 hooks/report-touched.sh           # session-touched hook
 docs/                             # client-side docs, one per contract
 skills/theme/                     # theme skill: SKILL.md, template.json, validate.mjs
+tests/                            # hook payloads asserted against lich's fixtures
 ```
 
 One set of hook scripts serves both harnesses — they live in `hooks/` and are referenced via `$CLAUDE_PLUGIN_ROOT/hooks/<script>`, a variable Codex sets too. [docs/providers.md](docs/providers.md) maps the layout and the two harnesses' event names.
@@ -81,3 +82,11 @@ Outside lich (env vars absent) the hooks are a no-op — the plugin is safe to i
 ```bash
 claude --plugin-dir .
 ```
+
+## Tests
+
+```bash
+node --test tests/*.test.mjs
+```
+
+Every hook script runs as a real subprocess, from the command line its registration spells, against a stub HTTP server — and the body it POSTs is asserted against [lich's contract fixtures](https://github.com/omartelo/lich/tree/main/docs/hooks/fixtures): an accepted shape, never a rejected one, the right endpoint and token, plus the client rules (no lich environment → no report; exit 0 when lich answers 500 or refuses the connection). The fixtures are vendored in `tests/fixtures/` by `tests/refresh-fixtures.sh`; CI diffs them against upstream so a contract that moves in lich goes red here.
diff --git a/hooks/report-title.sh b/hooks/report-title.sh
index 61943df..f84a5bc 100755
--- a/hooks/report-title.sh
+++ b/hooks/report-title.sh
@@ -24,6 +24,10 @@ if [ -z "$title" ]; then
     | head -n 1 | cut -c 1-80)
 fi
 
+# lich rejects a blank title (400): a Codex first line can be nothing but
+# spaces, and an ai-title could in principle be padded. Trim before deciding
+# there is a title at all — command substitution above only ate the newlines.
+title=$(printf '%s' "$title" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
 [ -n "$title" ] || exit 0
 
 body=$(jq -cn --arg sid "$LICH_SESSION_ID" --arg title "$title" \
diff --git a/tests/fixtures/session-start.jsonl b/tests/fixtures/session-start.jsonl
new file mode 100644
index 0000000..b0acea1
--- /dev/null
+++ b/tests/fixtures/session-start.jsonl
@@ -0,0 +1,9 @@
+{"name":"reported provider","body":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","provider":"codex"},"accept":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","provider":"codex"}}
+{"name":"absent provider defaults to claude","body":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01"},"accept":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","provider":"claude"}}
+{"name":"legacy claude_session_id is folded","body":{"session_id":"s1","claude_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c02"},"accept":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c02","provider":"claude"}}
+{"name":"provider_session_id wins over legacy","body":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","claude_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c02"},"accept":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","provider":"claude"}}
+{"name":"missing session_id","body":{"provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01"},"reject":"session_id is required"}
+{"name":"missing provider_session_id","body":{"session_id":"s1"},"reject":"provider_session_id is required"}
+{"name":"empty provider_session_id","body":{"session_id":"s1","provider_session_id":""},"reject":"provider_session_id is required"}
+{"name":"unregistered provider","body":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","provider":"aider"},"reject":"provider must be a registered provider id"}
+{"name":"malformed json","raw":"{","reject":"body must be a JSON object"}
diff --git a/tests/fixtures/session-state.jsonl b/tests/fixtures/session-state.jsonl
new file mode 100644
index 0000000..1725671
--- /dev/null
+++ b/tests/fixtures/session-state.jsonl
@@ -0,0 +1,10 @@
+{"name":"busy","body":{"session_id":"s1","state":"busy"},"accept":{"session_id":"s1","state":"busy"}}
+{"name":"done","body":{"session_id":"s1","state":"done"},"accept":{"session_id":"s1","state":"done"}}
+{"name":"waiting","body":{"session_id":"s1","state":"waiting"},"accept":{"session_id":"s1","state":"waiting"}}
+{"name":"idle","body":{"session_id":"s1","state":"idle"},"accept":{"session_id":"s1","state":"idle"}}
+{"name":"missing session_id","body":{"state":"busy"},"reject":"session_id is required"}
+{"name":"empty session_id","body":{"session_id":"","state":"busy"},"reject":"session_id is required"}
+{"name":"unknown state","body":{"session_id":"s1","state":"cooking"},"reject":"state must be one of busy, done, waiting, idle"}
+{"name":"missing state","body":{"session_id":"s1"},"reject":"state must be one of busy, done, waiting, idle"}
+{"name":"state is case sensitive","body":{"session_id":"s1","state":"Busy"},"reject":"state must be one of busy, done, waiting, idle"}
+{"name":"malformed json","raw":"{","reject":"body must be a JSON object"}
diff --git a/tests/fixtures/session-title.jsonl b/tests/fixtures/session-title.jsonl
new file mode 100644
index 0000000..2dc2361
--- /dev/null
+++ b/tests/fixtures/session-title.jsonl
@@ -0,0 +1,7 @@
+{"name":"ok","body":{"session_id":"s1","title":"Fix the replay ring overflow"},"accept":{"session_id":"s1","title":"Fix the replay ring overflow"}}
+{"name":"surrounding whitespace is trimmed","body":{"session_id":"s1","title":"  Fix the replay ring overflow\n"},"accept":{"session_id":"s1","title":"Fix the replay ring overflow"}}
+{"name":"missing session_id","body":{"title":"Fix the replay ring overflow"},"reject":"session_id is required"}
+{"name":"missing title","body":{"session_id":"s1"},"reject":"title is required and must not be blank"}
+{"name":"empty title","body":{"session_id":"s1","title":""},"reject":"title is required and must not be blank"}
+{"name":"blank title","body":{"session_id":"s1","title":"   \n"},"reject":"title is required and must not be blank"}
+{"name":"malformed json","raw":"{","reject":"body must be a JSON object"}
diff --git a/tests/fixtures/session-touched.jsonl b/tests/fixtures/session-touched.jsonl
new file mode 100644
index 0000000..00c8c84
--- /dev/null
+++ b/tests/fixtures/session-touched.jsonl
@@ -0,0 +1,5 @@
+{"name":"ok","body":{"session_id":"s1"},"accept":{"session_id":"s1"}}
+{"name":"extra fields are ignored","body":{"session_id":"s1","tool":"Edit"},"accept":{"session_id":"s1"}}
+{"name":"missing session_id","body":{},"reject":"session_id is required"}
+{"name":"empty session_id","body":{"session_id":""},"reject":"session_id is required"}
+{"name":"malformed json","raw":"{","reject":"body must be a JSON object"}
diff --git a/tests/hooks.test.mjs b/tests/hooks.test.mjs
new file mode 100644
index 0000000..9c184c8
--- /dev/null
+++ b/tests/hooks.test.mjs
@@ -0,0 +1,595 @@
+// Pins this plugin's hook scripts to lich's contract fixtures.
+//
+// lich owns the endpoints, this repository owns the scripts that build the
+// payloads. The fixtures in tests/fixtures/ are lich's, vendored verbatim
+// (tests/refresh-fixtures.sh); they are upstream truth and are never edited to
+// make a run green.
+//
+// Every case here drives a real script as a subprocess — the command line taken
+// from the hook registration a harness actually reads — against a stub HTTP
+// server, and asserts the body it POSTs.
+//
+// Run: node --test tests/
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+import { spawn, spawnSync } from 'node:child_process'
+import { readFileSync, writeFileSync, mkdtempSync, mkdirSync, symlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const ROOT = path.resolve(HERE, '..')
+
+const TOKEN = 'test-token'
+const LICH_SESSION_ID = 'lich-session-1'
+
+// ---------------------------------------------------------------- fixtures --
+
+/** endpoint → fixture file, per lich's docs/hooks/fixtures/README.md. */
+const FIXTURE_OF = {
+  '/hook': 'session-state',
+  '/session-start': 'session-start',
+  '/session-title': 'session-title',
+  '/session-touched': 'session-touched',
+}
+
+const readFixture = (name) =>
+  readFileSync(path.join(HERE, 'fixtures', `${name}.jsonl`), 'utf8')
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => JSON.parse(line))
+
+const CASES = Object.fromEntries(
+  Object.entries(FIXTURE_OF).map(([endpoint, file]) => [endpoint, readFixture(file)]),
+)
+
+const accepted = (endpoint) => CASES[endpoint].filter((c) => c.accept)
+const rejected = (endpoint) => CASES[endpoint].filter((c) => c.reject)
+
+// Enumerations come from the fixtures, not from a copy of them kept here: a
+// state or a provider that lich stops accepting stops being accepted below too.
+const STATES = new Set(accepted('/hook').map((c) => c.accept.state))
+const PROVIDERS = new Set(accepted('/session-start').map((c) => c.accept.provider))
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+const blank = (v) => typeof v !== 'string' || v.trim() === ''
+
+/**
+ * `reject` prose is documentation, not a matcher, so each rejected case is
+ * modelled here as a predicate: true means the body is the shape that case
+ * describes. A rejected case with no rule fails its own test below, so a new
+ * one upstream cannot slip through unmodelled.
+ */
+const REJECT_RULES = {
+  '/hook': {
+    'missing session_id': (b) => !('session_id' in b),
+    'empty session_id': (b) => b.session_id === '',
+    'missing state': (b) => !('state' in b),
+    'unknown state': (b) => 'state' in b && !STATES.has(b.state),
+    'state is case sensitive': (b) =>
+      typeof b.state === 'string' && !STATES.has(b.state) && STATES.has(b.state.toLowerCase()),
+    'malformed json': (b, raw) => !isJsonObject(raw),
+  },
+  '/session-start': {
+    'missing session_id': (b) => !('session_id' in b),
+    'missing provider_session_id': (b) => !('provider_session_id' in b) && !('claude_session_id' in b),
+    'empty provider_session_id': (b) => b.provider_session_id === '',
+    'unregistered provider': (b) => 'provider' in b && !PROVIDERS.has(b.provider),
+    'malformed json': (b, raw) => !isJsonObject(raw),
+  },
+  '/session-title': {
+    'missing session_id': (b) => !('session_id' in b),
+    'missing title': (b) => !('title' in b),
+    'empty title': (b) => b.title === '',
+    'blank title': (b) => 'title' in b && blank(b.title),
+    'malformed json': (b, raw) => !isJsonObject(raw),
+  },
+  '/session-touched': {
+    'missing session_id': (b) => !('session_id' in b),
+    'empty session_id': (b) => b.session_id === '',
+    'malformed json': (b, raw) => !isJsonObject(raw),
+  },
+}
+
+function isJsonObject(raw) {
+  try {
+    return isObject(JSON.parse(raw))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Compares a sent body against every `accept` case's `body` for the endpoint:
+ * same key set, and each value of the same class (a non-blank string stays a
+ * non-blank string). Values themselves are dynamic — session ids and titles are
+ * whatever the session happens to hold — so only shape is asserted here;
+ * enumerated values are pinned by the reject rules.
+ *
+ * Returns the name of the case it matches, or null.
+ */
+function matchingAcceptCase(endpoint, body) {
+  const shape = (o) =>
+    Object.keys(o)
+      .sort()
+      .map((k) => `${k}:${blank(o[k]) ? typeof o[k] + '(blank)' : typeof o[k]}`)
+      .join(',')
+  const sent = shape(body)
+  return accepted(endpoint).find((c) => c.body && shape(c.body) === sent)?.name ?? null
+}
+
+function assertContractHonoured(endpoint, request) {
+  assert.equal(request.method, 'POST')
+  assert.equal(
+    request.url,
+    `${endpoint}?token=${TOKEN}`,
+    `posted to ${request.url}, expected ${endpoint}?token=${TOKEN}`,
+  )
+  assert.match(request.headers['content-type'] ?? '', /application\/json/)
+
+  assert.ok(isJsonObject(request.raw), `body is not a JSON object: ${request.raw}`)
+  const body = JSON.parse(request.raw)
+
+  // 4. claude_session_id is a deprecated alias lich still folds for plugins
+  //    released before v0.3.0. Nothing shipping today emits it.
+  assert.ok(!('claude_session_id' in body), `body still sends claude_session_id: ${request.raw}`)
+
+  const match = matchingAcceptCase(endpoint, body)
+  assert.ok(match, `body matches no accepted shape for ${endpoint}: ${request.raw}`)
+
+  for (const [name, violates] of Object.entries(REJECT_RULES[endpoint])) {
+    assert.ok(!violates(body, request.raw), `body is the rejected shape "${name}": ${request.raw}`)
+  }
+  return { body, match }
+}
+
+// ------------------------------------------------------------------ harness --
+
+async function startStub({ status = 204 } = {}) {
+  const requests = []
+  const server = createServer((req, res) => {
+    let raw = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      raw += chunk
+    })
+    req.on('end', () => {
+      requests.push({ method: req.method, url: req.url, headers: req.headers, raw })
+      res.writeHead(status).end()
+    })
+  })
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
+  return {
+    requests,
+    port: server.address().port,
+    close: () => new Promise((resolve) => server.close(resolve)),
+  }
+}
+
+/** The ambient environment minus anything lich would inject. */
+const BASE_ENV = Object.fromEntries(
+  Object.entries(process.env).filter(([k]) => !k.startsWith('LICH_')),
+)
+
+/**
+ * Runs a hook exactly as its registration spells it: the command string from
+ * hooks.json / codex-hooks.json, through a shell, with $CLAUDE_PLUGIN_ROOT set.
+ */
+function runHook(command, { env = {}, stdin = '' } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn('/bin/sh', ['-c', command], {
+      env: { ...BASE_ENV, CLAUDE_PLUGIN_ROOT: ROOT, ...env },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (c) => {
+      stdout += c
+    })
+    child.stderr.on('data', (c) => {
+      stderr += c
+    })
+    child.stdin.on('error', () => {}) // a script that reads no stdin is fine
+    child.stdin.end(stdin)
+    child.on('close', (code) => resolve({ code, stdout, stderr }))
+  })
+}
+
+const lichEnv = (port) => ({
+  LICH_PORT: String(port),
+  LICH_TOKEN: TOKEN,
+  LICH_SESSION_ID,
+})
+
+async function withStub(fn, options) {
+  const stub = await startStub(options)
+  try {
+    return await fn(stub)
+  } finally {
+    await stub.close()
+  }
+}
+
+// A hook that reports never speaks on stdout: on Codex the session-state hook
+// rides PermissionRequest, where output and a non-zero exit are an answer to
+// the request rather than an observation.
+function assertSilentSuccess(result) {
+  assert.equal(result.code, 0, `exited ${result.code}: ${result.stderr}`)
+  assert.equal(result.stdout, '', `wrote to stdout: ${result.stdout}`)
+}
+
+// ------------------------------------------------------------ registrations --
+
+const HOOK_FILES = [
+  { provider: 'claude', file: 'hooks/hooks.json' },
+  { provider: 'codex', file: 'hooks/codex-hooks.json' },
+]
+
+const SCRIPTS = {
+  'report-state.sh': '/hook',
+  'report-session-start.sh': '/session-start',
+  'report-title.sh': '/session-title',
+  'report-touched.sh': '/session-touched',
+}
+
+function registrations() {
+  const out = []
+  for (const { provider, file } of HOOK_FILES) {
+    const json = JSON.parse(readFileSync(path.join(ROOT, file), 'utf8'))
+    for (const [event, groups] of Object.entries(json.hooks)) {
+      for (const group of groups) {
+        for (const hook of group.hooks) {
+          const script = Object.keys(SCRIPTS).find((s) => hook.command.includes(s))
+          assert.ok(script, `unknown script in ${file}: ${hook.command}`)
+          out.push({
+            provider,
+            file,
+            event,
+            matcher: group.matcher,
+            command: hook.command,
+            script,
+            endpoint: SCRIPTS[script],
+            argument: hook.command.trim().split(/\s+/).slice(1).join(' '),
+          })
+        }
+      }
+    }
+  }
+  return out
+}
+
+const REGISTRATIONS = registrations()
+
+// ------------------------------------------------------------- transcripts --
+
+const TMP = mkdtempSync(path.join(tmpdir(), 'lich-plugin-test-'))
+
+/** Claude Code keeps its generated title in the transcript as an ai-title line. */
+function claudeTranscript(title, name = 'claude.jsonl') {
+  const file = path.join(TMP, name)
+  const lines = [
+    JSON.stringify({ type: 'user', message: { role: 'user', content: 'hi' } }),
+    ...(title === null ? [] : [JSON.stringify({ type: 'ai-title', aiTitle: title })]),
+    JSON.stringify({ type: 'assistant', message: { role: 'assistant', content: 'ok' } }),
+  ]
+  writeFileSync(file, lines.join('\n') + '\n')
+  return file
+}
+
+/** Codex generates no title: its rollout carries the first user message. */
+function codexTranscript(message, name = 'codex.jsonl') {
+  const file = path.join(TMP, name)
+  const lines = [
+    JSON.stringify({ timestamp: '2026-08-10T12:00:00.000Z', type: 'session_meta', payload: {} }),
+    ...(message === null
+      ? []
+      : [
+          JSON.stringify({
+            timestamp: '2026-08-10T12:00:01.000Z',
+            type: 'event_msg',
+            payload: { type: 'user_message', message, kind: 'plain' },
+          }),
+        ]),
+  ]
+  writeFileSync(file, lines.join('\n') + '\n')
+  return file
+}
+
+/**
+ * A PATH holding every tool the hooks use except the named one — for the
+ * fallbacks a script keeps for machines where a tool is absent.
+ */
+function binWithout(missing) {
+  const dir = path.join(TMP, `bin-without-${missing}`)
+  mkdirSync(dir, { recursive: true })
+  for (const tool of ['sh', 'sed', 'grep', 'cut', 'head', 'tail', 'curl', 'jq']) {
+    if (tool === missing) continue
+    const found = spawnSync('sh', ['-c', `command -v ${tool}`], { encoding: 'utf8' }).stdout.trim()
+    if (!found) continue
+    try {
+      symlinkSync(found, path.join(dir, tool))
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e
+    }
+  }
+  return dir
+}
+
+const PROVIDER_SESSION_ID = {
+  claude: '9f1c7c1e-8f2a-4c3b-9d5e-2a7b6c4d1e05',
+  codex: '018f9c5a-0000-7000-9a3b-1c2d3e4f5c01',
+}
+
+const TRANSCRIPT = {
+  claude: claudeTranscript('Fix the replay ring overflow'),
+  codex: codexTranscript('Fix the replay ring overflow\nand its second line'),
+}
+
+/** What the harness puts on stdin for the event this registration rides. */
+function stdinFor({ provider, event }) {
+  return JSON.stringify({
+    session_id: PROVIDER_SESSION_ID[provider],
+    transcript_path: TRANSCRIPT[provider],
+    cwd: ROOT,
+    hook_event_name: event,
+  })
+}
+
+// ----------------------------------------------------------------- the suite --
+
+test('the vendored fixtures parse and carry exactly one body and one verdict', () => {
+  for (const [endpoint, cases] of Object.entries(CASES)) {
+    assert.ok(cases.length > 0, `${endpoint} has no cases`)
+    const names = new Set()
+    for (const c of cases) {
+      assert.ok(typeof c.name === 'string' && c.name !== '', `case without a name in ${endpoint}`)
+      assert.ok(!names.has(c.name), `duplicate case name "${c.name}" in ${endpoint}`)
+      names.add(c.name)
+      assert.equal(
+        ('body' in c ? 1 : 0) + ('raw' in c ? 1 : 0),
+        1,
+        `case "${c.name}" must carry exactly one of body/raw`,
+      )
+      assert.equal(
+        ('accept' in c ? 1 : 0) + ('reject' in c ? 1 : 0),
+        1,
+        `case "${c.name}" must carry exactly one of accept/reject`,
+      )
+    }
+  }
+  assert.deepEqual([...STATES].sort(), ['busy', 'done', 'idle', 'waiting'])
+  assert.deepEqual([...PROVIDERS].sort(), ['claude', 'codex'])
+})
+
+test('every rejected case is modelled by a client-side rule', () => {
+  for (const endpoint of Object.keys(CASES)) {
+    for (const c of rejected(endpoint)) {
+      assert.ok(
+        c.name in REJECT_RULES[endpoint],
+        `${endpoint} fixture rejects "${c.name}" (${c.reject}) with no rule in REJECT_RULES — ` +
+          `the contract moved upstream; model it here before trusting the suite`,
+      )
+    }
+  }
+})
+
+test('every script is registered by both providers', () => {
+  for (const provider of ['claude', 'codex']) {
+    const scripts = new Set(REGISTRATIONS.filter((r) => r.provider === provider).map((r) => r.script))
+    assert.deepEqual([...scripts].sort(), Object.keys(SCRIPTS).sort(), `${provider} misses a script`)
+  }
+})
+
+test('every registered state argument is an accepted state', () => {
+  const sent = REGISTRATIONS.filter((r) => r.script === 'report-state.sh').map((r) => r.argument)
+  assert.ok(sent.length > 0)
+  for (const state of sent) assert.ok(STATES.has(state), `registration reports unknown state "${state}"`)
+  // Both registrations wire up the whole vocabulary; Codex's SessionEnd never
+  // fires today, but the entry is deliberate (docs/providers.md).
+  for (const provider of ['claude', 'codex']) {
+    const states = new Set(
+      REGISTRATIONS.filter((r) => r.provider === provider && r.script === 'report-state.sh').map(
+        (r) => r.argument,
+      ),
+    )
+    assert.deepEqual([...states].sort(), [...STATES].sort(), `${provider} misses a state`)
+  }
+})
+
+test('every registered provider argument is a registered provider', () => {
+  for (const r of REGISTRATIONS.filter((r) => r.script === 'report-session-start.sh')) {
+    assert.ok(PROVIDERS.has(r.argument), `registration reports unknown provider "${r.argument}"`)
+    assert.equal(r.argument, r.provider, `${r.file} reports the wrong provider`)
+  }
+})
+
+// 1-4: shape, endpoint, token, no deprecated alias — for every script, as each
+// harness registers it.
+for (const registration of REGISTRATIONS) {
+  const { provider, event, script, endpoint, argument, matcher } = registration
+  const label = [provider, event, script, argument, matcher && `matcher ${matcher}`]
+    .filter(Boolean)
+    .join(' ')
+
+  test(`${label} posts an accepted payload`, async () => {
+    await withStub(async (stub) => {
+      const result = await runHook(registration.command, {
+        env: lichEnv(stub.port),
+        stdin: stdinFor(registration),
+      })
+      assertSilentSuccess(result)
+      assert.equal(stub.requests.length, 1, `sent ${stub.requests.length} requests, expected 1`)
+
+      const { body } = assertContractHonoured(endpoint, stub.requests[0])
+      assert.equal(body.session_id, LICH_SESSION_ID)
+      if (script === 'report-state.sh') assert.equal(body.state, argument)
+      if (script === 'report-session-start.sh') {
+        assert.equal(body.provider, provider)
+        assert.equal(body.provider_session_id, PROVIDER_SESSION_ID[provider])
+      }
+      if (script === 'report-title.sh') assert.equal(body.title, 'Fix the replay ring overflow')
+    })
+  })
+}
+
+test('session-start falls back to claude when the registration passes no provider', async () => {
+  await withStub(async (stub) => {
+    const result = await runHook(`"${ROOT}/hooks/report-session-start.sh"`, {
+      env: lichEnv(stub.port),
+      stdin: stdinFor({ provider: 'claude', event: 'SessionStart' }),
+    })
+    assertSilentSuccess(result)
+    const { body } = assertContractHonoured('/session-start', stub.requests[0])
+    assert.equal(body.provider, 'claude')
+  })
+})
+
+test('session-start parses the payload without jq', async () => {
+  // Windows ships sed (Git Bash) but rarely jq; the script falls back to sed.
+  await withStub(async (stub) => {
+    const result = await runHook(`"${ROOT}/hooks/report-session-start.sh" claude`, {
+      env: { ...lichEnv(stub.port), PATH: binWithout('jq') },
+      stdin: stdinFor({ provider: 'claude', event: 'SessionStart' }),
+    })
+    assertSilentSuccess(result)
+    assert.equal(stub.requests.length, 1)
+    const { body } = assertContractHonoured('/session-start', stub.requests[0])
+    assert.equal(body.provider_session_id, PROVIDER_SESSION_ID.claude)
+  })
+})
+
+test('session-start no-ops when the payload carries no session id', async () => {
+  await withStub(async (stub) => {
+    const result = await runHook(`"${ROOT}/hooks/report-session-start.sh" codex`, {
+      env: lichEnv(stub.port),
+      stdin: JSON.stringify({ transcript_path: TRANSCRIPT.codex }),
+    })
+    assertSilentSuccess(result)
+    assert.equal(stub.requests.length, 0, 'sent a report with no provider session id')
+  })
+})
+
+// A title the contract calls blank must never leave the client: the fixture
+// rejects "", "   \n" and a missing field alike.
+const NO_TITLE = [
+  ['claude transcript without an ai-title line', () => claudeTranscript(null, 'no-title.jsonl')],
+  ['claude ai-title that is empty', () => claudeTranscript('', 'empty-title.jsonl')],
+  ['claude ai-title that is whitespace', () => claudeTranscript('   ', 'blank-title.jsonl')],
+  ['codex rollout without a user message', () => codexTranscript(null, 'no-message.jsonl')],
+  ['codex first line that is whitespace', () => codexTranscript('   \nreal work', 'blank-line.jsonl')],
+  ['codex message that is a newline', () => codexTranscript('\nreal work', 'leading-nl.jsonl')],
+]
+
+for (const [label, make] of NO_TITLE) {
+  test(`session-title stays silent: ${label}`, async () => {
+    await withStub(async (stub) => {
+      const result = await runHook(`"${ROOT}/hooks/report-title.sh"`, {
+        env: lichEnv(stub.port),
+        stdin: JSON.stringify({ session_id: 's', transcript_path: make() }),
+      })
+      assertSilentSuccess(result)
+      assert.equal(
+        stub.requests.length,
+        0,
+        `posted a blank title, which the contract rejects: ${stub.requests[0]?.raw}`,
+      )
+    })
+  })
+}
+
+test('session-title trims the title it reports', async () => {
+  await withStub(async (stub) => {
+    const file = claudeTranscript('  Fix the replay ring overflow  ', 'padded-title.jsonl')
+    const result = await runHook(`"${ROOT}/hooks/report-title.sh"`, {
+      env: lichEnv(stub.port),
+      stdin: JSON.stringify({ session_id: 's', transcript_path: file }),
+    })
+    assertSilentSuccess(result)
+    const { body } = assertContractHonoured('/session-title', stub.requests[0])
+    assert.equal(body.title, 'Fix the replay ring overflow')
+  })
+})
+
+test('session-title escapes a title that would break the JSON body', async () => {
+  await withStub(async (stub) => {
+    const file = claudeTranscript('Fix "quoted" \\ and \ttabbed', 'quoted-title.jsonl')
+    const result = await runHook(`"${ROOT}/hooks/report-title.sh"`, {
+      env: lichEnv(stub.port),
+      stdin: JSON.stringify({ session_id: 's', transcript_path: file }),
+    })
+    assertSilentSuccess(result)
+    const { body } = assertContractHonoured('/session-title', stub.requests[0])
+    assert.equal(body.title, 'Fix "quoted" \\ and \ttabbed')
+  })
+})
+
+test('session-title no-ops when the transcript is missing', async () => {
+  await withStub(async (stub) => {
+    const result = await runHook(`"${ROOT}/hooks/report-title.sh"`, {
+      env: lichEnv(stub.port),
+      stdin: JSON.stringify({ session_id: 's', transcript_path: path.join(TMP, 'absent.jsonl') }),
+    })
+    assertSilentSuccess(result)
+    assert.equal(stub.requests.length, 0)
+  })
+})
+
+// 5: the client rules — a hook must never block or fail the user's turn.
+const EVERY_SCRIPT = [
+  { script: 'report-state.sh', argument: 'busy' },
+  { script: 'report-session-start.sh', argument: 'claude' },
+  { script: 'report-title.sh', argument: '' },
+  { script: 'report-touched.sh', argument: '' },
+]
+
+const PARTIAL_ENVS = {
+  'no lich variables at all': {},
+  'only LICH_PORT': { LICH_PORT: '1' },
+  'no LICH_TOKEN': { LICH_PORT: '1', LICH_SESSION_ID },
+  'no LICH_SESSION_ID': { LICH_PORT: '1', LICH_TOKEN: TOKEN },
+  'blank LICH_SESSION_ID': { LICH_PORT: '1', LICH_TOKEN: TOKEN, LICH_SESSION_ID: '' },
+}
+
+for (const { script, argument } of EVERY_SCRIPT) {
+  for (const [label, env] of Object.entries(PARTIAL_ENVS)) {
+    test(`${script} no-ops outside lich: ${label}`, async () => {
+      await withStub(async (stub) => {
+        const result = await runHook(`"${ROOT}/hooks/${script}" ${argument}`.trim(), {
+          // LICH_PORT points at the stub so a leak would be caught, not refused.
+          env: { ...env, ...(('LICH_PORT' in env) ? { LICH_PORT: String(stub.port) } : {}) },
+          stdin: stdinFor({ provider: 'claude', event: 'SessionStart' }),
+        })
+        assertSilentSuccess(result)
+        assert.equal(stub.requests.length, 0, 'reported without a full lich environment')
+      })
+    })
+  }
+
+  test(`${script} exits 0 when lich answers 500`, async () => {
+    await withStub(
+      async (stub) => {
+        const result = await runHook(`"${ROOT}/hooks/${script}" ${argument}`.trim(), {
+          env: lichEnv(stub.port),
+          stdin: stdinFor({ provider: 'claude', event: 'SessionStart' }),
+        })
+        assertSilentSuccess(result)
+        assert.equal(stub.requests.length, 1)
+      },
+      { status: 500 },
+    )
+  })
+
+  test(`${script} exits 0 when the connection is refused`, async () => {
+    const stub = await startStub()
+    const { port } = stub
+    await stub.close() // nothing listens on that port any more
+    const result = await runHook(`"${ROOT}/hooks/${script}" ${argument}`.trim(), {
+      env: lichEnv(port),
+      stdin: stdinFor({ provider: 'claude', event: 'SessionStart' }),
+    })
+    assertSilentSuccess(result)
+  })
+}
diff --git a/tests/refresh-fixtures.sh b/tests/refresh-fixtures.sh
new file mode 100755
index 0000000..4ca8e1d
--- /dev/null
+++ b/tests/refresh-fixtures.sh
@@ -0,0 +1,19 @@
+#!/bin/sh
+# Refreshes the vendored copies of lich's hook-contract fixtures.
+#
+# The fixtures are canonical in the lich repository (docs/hooks/fixtures/
+# there). This repository only vendors them so the test suite never needs the
+# network. Run this after a contract change lands in lich; CI diffs the copy
+# against upstream and fails on drift.
+#
+# Never hand-edit a fixture to get a green run — a fixture moves in lich, and
+# only because the contract moved.
+set -eu
+
+base=https://raw.githubusercontent.com/omartelo/lich/main/docs/hooks/fixtures
+dir=$(CDPATH= cd -- "$(dirname -- "$0")/fixtures" && pwd)
+
+for name in session-state session-start session-title session-touched; do
+  curl -fsSL "$base/$name.jsonl" -o "$dir/$name.jsonl"
+  echo "refreshed $name.jsonl"
+done