diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..7409b64
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,77 @@
+name: ci
+
+# macOS only, deliberately: mcs is a Swift/Homebrew tool that installs on macOS,
+# so it is the only platform that can actually install this pack. The suite runs
+# the hooks exactly as mcs does, by executing them and letting the shebang pick
+# the interpreter.
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        # 22.6 is the floor: `--experimental-strip-types` does not exist below it,
+        # and a bare '22' resolves to current 22.x, which cannot reach that range.
+        node: ['22.6.0', '22', '24']
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: node is new enough to strip types
+        run: |
+          command -v git >/dev/null || { echo "::error::git is required"; exit 1; }
+          node --experimental-strip-types -e 'const [maj, min] = process.versions.node.split(".").map(Number);
+            if (maj < 22 || (maj === 22 && min < 6)) { console.error("::error::node " + process.versions.node + " cannot strip types"); process.exit(1); }
+            console.log("node " + process.versions.node + " strips types");'
+
+      - name: install typecheck deps (CI-only, never shipped)
+        run: npm install --no-save --silent typescript@5.9.2 @types/node@22.9.0
+
+      - name: typecheck
+        run: npm run typecheck
+
+      - name: unit, contract and behaviour tests
+        run: npm test
+
+      # A migration artifact: it pinned the premise that commit subjects were
+      # unchanged by the port. Cheap to keep, not load-bearing going forward.
+      - name: the hostname equivalence holds on this runner
+        run: |
+          from_shell=$(hostname -s)
+          from_node=$(node -e 'process.stdout.write(require("node:os").hostname().split(".")[0])')
+          echo "shell='$from_shell' node='$from_node'"
+          [ "$from_shell" = "$from_node" ] || { echo "::error::hostname -s and os.hostname() disagree"; exit 1; }
+
+      # The pack contains no shell at all. Hooks and pack scripts are TypeScript
+      # executed through their shebang.
+      - name: no shell crept back in
+        run: |
+          stray=$(find . -name '*.sh' -not -path './node_modules/*' -not -path './.git/*' || true)
+          if [ -n "$stray" ]; then
+            echo "::error::this pack contains no shell scripts"
+            echo "$stray"
+            exit 1
+          fi
+
+      # A test that writes outside its temp dir is a bug wherever it lands.
+      - name: the test run left the working tree clean
+        run: |
+          residue=$(git status --porcelain --untracked-files=all)
+          if [ -n "$residue" ]; then
+            echo "::error::the test run left files behind"
+            echo "$residue"
+            exit 1
+          fi
diff --git a/.gitignore b/.gitignore
index 10179f4..e950fdf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,6 @@
 *.swo
 .idea/
 .vscode/
+
+# Node typecheck deps (CI + local only; runtime is zero-deps)
+node_modules/
diff --git a/README.md b/README.md
index 1528c70..e725485 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Shared Memories
+# 🧠 Shared Memories
 
 A [tech pack](https://github.com/mcs-cli/mcs) that auto-syncs Claude Code's `.claude/memories/` across a team via a dedicated shared git repo. Captures are handled by [`mcs-cli/memory`](https://github.com/mcs-cli/memory) (the `continuous-learning` skill + semantic retrieval); this pack **shares** those captures across the team without anyone remembering to commit or push.
 
@@ -6,12 +6,14 @@ Built for the [`mcs`](https://github.com/mcs-cli/mcs) configuration engine.
 
 ```
 identifier: shared-memories
-requires:   mcs >= 2026.4.12
+requires:   mcs >= 2026.9.3
 ```
 
+**Contents** — [When is this useful?](#-when-is-this-useful) · [The problem](#-the-problem) · [How it works](#-how-it-works) · [What's included](#-whats-included) · [Installation](#-installation) · [Directory structure](#-directory-structure) · [Migration](#-migration-from-an-existing-local-memories-folder) · [Side branches](#-optional-push-to-a-side-branch) · [Auto-push modes](#-auto-push-modes) · [Deletions](#-intentional-deletion-workflow) · [Troubleshooting](#-troubleshooting) · [Development](#-development)
+
 ---
 
-## When Is This Useful?
+## 🤔 When Is This Useful?
 
 **You probably don't need this pack if** your team commits `.claude/memories/` directly into the project repo — normal git workflow already shares those memories across the team and this pack adds nothing.
 
@@ -23,7 +25,7 @@ requires:   mcs >= 2026.4.12
 
 ---
 
-## The Problem
+## 🧩 The Problem
 
 Claude Code's `.claude/memories/` is great — you accumulate `learning_*.md` and `decision_*.md` files and Claude gets smarter about your codebase over time. But memories are **per-engineer**: when someone figures out a gnarly integration quirk or pins down a subtle architecture decision, only they benefit.
 
@@ -32,36 +34,25 @@ The obvious fix is a shared git repo. Two friction points kill adoption:
 1. **Remembering to push.** People forget. Memories sit on laptops for weeks.
 2. **Branch protection on the shared repo.** If every Claude turn needs a PR + ticket + approval, nobody will bother pushing their tiny observations.
 
-## The Solution
+## 🔁 The Solution
 
 This pack implements a **closed-loop sharing system** that pulls the latest team memories at session start and pushes new ones when Claude finishes a turn.
 
-```
-                             SHARED MEMORIES LOOP
-
- ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
- │   SESSION    │     │   TEAM KB    │     │     WORK     │     │     STOP     │
- │    START     │────>│    PULL      │────>│   SESSION    │────>│  AUTO-PUSH   │
- └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
-        ^                    |                    |                     |
-        |                    |                    |     filename guard  |
-        |                    |                    |     + configurable  |
-        |                    v                    v     push policy     v
-        |             ┌────────────────────────────────────────────────────┐
-        |             │              <shared memories repo>                 │
-        |             │  memories/                                          │
-        |             │    learning_background_task_watchdog_timeout.md     │
-        +─────────────│    learning_orm_batch_insert_memory_spike.md        │
-                      │    decision_architecture_mvvm_coordinators.md       │
-                      │    ...                                              │
-                      └────────────────────────────────────────────────────┘
+```mermaid
+flowchart TD
+    S([Session starts]) --> P["SessionStart hook<br/>git pull --ff-only"]
+    P --> W["Work session<br/>continuous-learning writes<br/>learning_*.md · decision_*.md"]
+    W --> T["Stop hook<br/>auto-push"]
+    T -->|"filename guard<br/>+ configurable push policy"| R
+    R[("shared memories repo — memories/<br/><br/>learning_background_task_watchdog_timeout.md<br/>learning_orm_batch_insert_memory_spike.md<br/>decision_architecture_mvvm_coordinators.md<br/>…")]
+    R -->|"teammates fast-forward at<br/>their next session start"| P
 ```
 
 Captures still come from [`mcs-cli/memory`](https://github.com/mcs-cli/memory). This pack is the distribution layer that makes them team-shared.
 
 ---
 
-## How It Works
+## 🔩 How It Works
 
 ### The Pieces
 
@@ -82,7 +73,7 @@ Captures still come from [`mcs-cli/memory`](https://github.com/mcs-cli/memory).
 
 3. **During work** — Claude uses the [`continuous-learning`](https://github.com/mcs-cli/memory) skill to write new `learning_*.md` / `decision_*.md` files
 
-4. **Claude finishes a turn** — the Stop hook collects dirty files and dispatches by mode (`MEMORIES_AUTOPUSH_MODE`, see [Auto-Push Modes](#auto-push-modes)):
+4. **Claude finishes a turn** — the Stop hook collects dirty files and dispatches by mode (`MEMORIES_AUTOPUSH_MODE`, see [Auto-Push Modes](#-auto-push-modes)):
    - **Naming guardrail (all modes)** — any file failing `^memories/(learning|decision)_[a-zA-Z0-9_-]+\.md$` halts everything until renamed
    - **`auto` (default)** — adds/mods auto-pushed; deletions parked in the working tree for manual review
    - **`full`** — adds/mods AND deletions auto-pushed in one commit
@@ -90,17 +81,37 @@ Captures still come from [`mcs-cli/memory`](https://github.com/mcs-cli/memory).
 
 5. **Next session** — teammates pull your new memories via SessionStart and the loop continues
 
+The Stop hook in full, since it is where all the policy lives:
+
+```mermaid
+flowchart TD
+    A([Claude finishes a turn]) --> B{"anything uncommitted<br/>or unpushed?"}
+    B -->|no| Z([exit 0])
+    B -->|yes| C{"every dirty file matches<br/>memories/learning_*.md<br/>or memories/decision_*.md?"}
+    C -->|no| D["list the offenders,<br/>push nothing"] --> Z
+    C -->|yes| E{MEMORIES_AUTOPUSH_MODE}
+    E -->|auto| F["stage adds and mods,<br/>park deletions for review"]
+    E -->|full| G["stage everything,<br/>deletions included"]
+    E -->|review| H["print the per-file report,<br/>commit nothing"]
+    F --> I["commit · pull --rebase --autostash · push<br/>retry with jitter if rejected"]
+    G --> I
+    H --> Z
+    I --> Z
+```
+
 ---
 
-## What's Included
+## 📦 What's Included
 
 ### Session Hooks
 
 | Hook | Event | What It Does |
 |------|-------|-------------|
-| **memories_pull.sh** | `SessionStart` | Fast-forwards the shared memories checkout; emits a mode-aware warning if previous state is stuck (or, in `review` mode, summarises pending review) |
-| **memories_autopush.sh** | `Stop` (async) | Dispatches by `MEMORIES_AUTOPUSH_MODE` mode (`auto` / `full` / `review`); filename guardrail applies in every mode |
-| **memories_announce.sh** | `PostToolUse` (Write/Edit/MultiEdit) | In `review` mode only, surfaces the just-written memory to Claude's context so it mentions pending review in chat. Silent in `auto` and `full` |
+| **pull.mts** | `SessionStart` | Fast-forwards the shared memories checkout; emits a mode-aware warning if previous state is stuck (or, in `review` mode, summarises pending review) |
+| **autopush.mts** | `Stop` (async) | Dispatches by `MEMORIES_AUTOPUSH_MODE` mode (`auto` / `full` / `review`); filename guardrail applies in every mode |
+| **announce.mts** | `PostToolUse` (Write/Edit/MultiEdit) | In `review` mode only, surfaces the just-written memory to Claude's context so it mentions pending review in chat. Silent in `auto` and `full` |
+
+Each runs as `node --experimental-strip-types --disable-warning=ExperimentalWarning <path>`: mcs prefixes the interpreter the hook declares in `hookInterpreter`, and never looks at the shebang. They install to `.claude/hooks/shared-memories/`, with the library they import beside them in `lib/`.
 
 ### Slash Commands
 
@@ -112,7 +123,7 @@ Captures still come from [`mcs-cli/memory`](https://github.com/mcs-cli/memory).
 
 | Script | When | What It Does |
 |--------|------|-------------|
-| **configure-memories.sh** | `mcs sync` | Sparse-clones the shared repo, sets up the symlink, migrates any pre-existing `.claude/memories/` into the shared folder |
+| **configure-memories.ts** | `mcs sync` | Sparse-clones the shared repo, sets up the symlink, migrates any pre-existing `.claude/memories/` into the shared folder |
 
 ### CLAUDE.local.md Section
 
@@ -131,15 +142,18 @@ Captures still come from [`mcs-cli/memory`](https://github.com/mcs-cli/memory).
 
 | Dep | Via |
 |-----|-----|
-| **jq** | brew |
+| **Node.js 22.6+** | brew |
+
+Node runs the TypeScript directly — there is no build step, no `node_modules`, and no runtime dependencies.
 
 ---
 
-## Installation
+## 🚀 Installation
 
 ### Prerequisites
 
 - macOS
+- Node.js 22.6 or newer (where `--experimental-strip-types` landed)
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
 - [mcs](https://github.com/mcs-cli/mcs) CLI
 - [`mcs-cli/memory`](https://github.com/mcs-cli/memory) (companion capture pack — produces the `learning_*.md` / `decision_*.md` files this pack shares)
@@ -169,7 +183,7 @@ During `mcs sync`, you'll be prompted for:
 |--------|-------------|---------|
 | **MEMORIES_REPO_URL** | Clone URL for the shared memories repo, e.g. `git@github.com:org/memories.git` | *(required)* |
 | **MEMORIES_BRANCH** | Branch that holds the memory files and this pack | `main` |
-| **MEMORIES_AUTOPUSH_MODE** | Stop-hook behavior — `auto` (writes auto-pushed, deletions parked), `full` (writes + deletions auto-pushed), or `review` (nothing auto, per-turn report). See [Auto-Push Modes](#auto-push-modes). | `auto` |
+| **MEMORIES_AUTOPUSH_MODE** | Stop-hook behavior — `auto` (writes auto-pushed, deletions parked), `full` (writes + deletions auto-pushed), or `review` (nothing auto, per-turn report). See [Auto-Push Modes](#-auto-push-modes). | `auto` |
 
 > **Install per-project, not globally.** Run `mcs sync` from each project's root (the directory that contains `.claude/`, not `.claude/` itself) — do **not** install this pack into your user-level `~/.claude/` directory.
 >
@@ -182,7 +196,7 @@ During `mcs sync`, you'll be prompted for:
 
 ---
 
-## Directory Structure
+## 📁 Directory Structure
 
 ```
 shared-memories/
@@ -191,22 +205,33 @@ shared-memories/
 │   └── approve-memories.md          # Slash command for review-mode approval
 ├── config/
 │   └── settings.json                # Templated env block — ships MEMORIES_AUTOPUSH_MODE
-├── hooks/
-│   ├── memories_pull.sh             # SessionStart: pull + stuck-state warning
-│   ├── memories_autopush.sh         # Stop: auto-commit + push (async)
-│   └── memories_announce.sh         # PostToolUse: review-mode nudge to Claude (sync)
-├── scripts/
-│   ├── configure-memories.sh        # Sparse clone + symlink + migration
-│   ├── doctor-memories.sh           # Setup health check
-│   └── doctor-memories-remote.sh    # Remote-access health check
-└── templates/
-    └── instructions.md              # CLAUDE.local.md section — what this dir is
+├── runtime/                         # Installed to .claude/hooks/shared-memories/
+│   ├── pull.mts                     # SessionStart: pull + stuck-state warning
+│   ├── autopush.mts                 # Stop: auto-commit + push (async)
+│   ├── announce.mts                 # PostToolUse: review-mode nudge to Claude (sync)
+│   └── lib/                         # git, paths, naming, mode, pending, report, push
+├── scripts/                         # Run in place from the pack checkout
+│   ├── configure-memories.ts        # Sparse clone + symlink + migration
+│   ├── doctor-memories.ts           # Setup health check
+│   └── doctor-memories-remote.ts    # Remote-access health check
+├── tests/                           # node:test — unit, contract and behaviour
+│   └── golden/                      # Behaviour recordings the suite checks against
+├── templates/
+│   └── instructions.md              # CLAUDE.local.md section — what this dir is
+├── .github/workflows/ci.yml         # macOS × Node 22.6/22/24
+├── package.json                     # No dependencies; test + typecheck scripts
+└── tsconfig.json                    # Strict, erasable-syntax-only, no emit
 ```
 
 On engineer disks, the pack materializes as:
 
 ```
 <project>/.claude/
+├── hooks/shared-memories/           # run by mcs via each hook's declared hookInterpreter
+│   ├── pull.mts
+│   ├── autopush.mts
+│   ├── announce.mts
+│   └── lib/                         # imported as ./lib/… by the entries beside it
 ├── .memories-repo/                  # sparse clone of MEMORIES_BRANCH
 │   ├── README.md, LICENSE, etc.     # any root-level files your repo ships
 │   └── memories/
@@ -219,7 +244,7 @@ The clone uses `--sparse --filter=blob:none --single-branch` so only the `memori
 
 ---
 
-## Migration From an Existing Local Memories Folder
+## 🚚 Migration From an Existing Local Memories Folder
 
 Engineers who already have `.claude/memories/` populated (from `mcs-cli/memory`, Claude Code's native memory, or manual use) are handled automatically on first `mcs sync`:
 
@@ -230,7 +255,21 @@ Engineers who already have `.claude/memories/` populated (from `mcs-cli/memory`,
 5. Well-named migrated files are auto-committed and pushed so they immediately become team knowledge
 6. If nothing is left in the backup dir, it's cleaned up automatically
 
-If any step fails partway, an `ERR` trap restores the original folder from the backup — you're never left with a broken setup and no memories.
+If any step fails partway, the failure path restores the original folder from the backup — you're never left with a broken setup and no memories.
+
+Each file in the backup takes one of four paths:
+
+```mermaid
+flowchart TD
+    A["a file in the migration backup"] --> B{"a file of that name<br/>already in the shared repo?"}
+    B -->|yes| C["skip — the shared copy wins,<br/>yours stays in the backup"]
+    B -->|no| D{"deleted somewhere in<br/>the branch's history?"}
+    D -->|yes| E["hold back, naming the<br/>commit that removed it"]
+    D -->|no| F["import into memories/"]
+    F --> G{"matches the naming rule?"}
+    G -->|yes| H["auto-commit and push"]
+    G -->|no| I["leave untracked,<br/>with a rename nudge"]
+```
 
 ### Why previously-deleted files are held back
 
@@ -261,7 +300,7 @@ A separate gap worth knowing about when you audit: filenames alone under-count d
 
 ---
 
-## Optional: Push to a Side Branch
+## 🌿 Optional: Push to a Side Branch
 
 If your org enforces PR + ticket + approval on the default branch of your memories repo, every Claude Stop auto-pushing to it would turn each memory into a PR. That kills adoption.
 
@@ -280,7 +319,7 @@ Normal commits (including ones that delete files via `memory-audit`) are unaffec
 
 ---
 
-## Auto-Push Modes
+## 🚦 Auto-Push Modes
 
 The Stop hook's behavior is set during `mcs sync` via the `MEMORIES_AUTOPUSH_MODE` prompt. The chosen value is written to `.claude/settings.local.json`'s `env` block (per-user / project-local). To change modes later, re-run `mcs sync` and pick a different value, or edit `.claude/settings.local.json` directly.
 
@@ -311,13 +350,13 @@ Discard local changes: …
 
 The same pending set is reported once per session — repeated turns within the session stay silent so the report doesn't spam every prompt. SessionStart resets the dedupe so unresolved changes re-surface in the next session instead of being buried forever.
 
-In `review` mode, Claude is also told about each memory write through a separate PostToolUse hook (`memories_announce.sh`), so it can proactively mention pending review in the same turn and invoke `/approve-memories` when you confirm — without needing to wait for the terminal report. The terminal report and the in-conversation nudge are independent channels: the report goes to your terminal, the nudge goes to Claude's context. `auto` and `full` modes keep both channels silent.
+In `review` mode, Claude is also told about each memory write through a separate PostToolUse hook (`announce.mts`), so it can proactively mention pending review in the same turn and invoke `/approve-memories` when you confirm — without needing to wait for the terminal report. The terminal report and the in-conversation nudge are independent channels: the report goes to your terminal, the nudge goes to Claude's context. `auto` and `full` modes keep both channels silent.
 
 Pull is always automatic regardless of mode — incoming team memories arrive at session start.
 
 ---
 
-## Intentional Deletion Workflow
+## 🧹 Intentional Deletion Workflow
 
 When you legitimately want to remove stale memories (typically after running the `memory-audit` skill from `mcs-cli/memory`), invoke the slash command:
 
@@ -333,7 +372,7 @@ If your workflow makes the friction unnecessary, set `MEMORIES_AUTOPUSH_MODE=ful
 
 ---
 
-## Troubleshooting
+## 🔧 Troubleshooting
 
 ```bash
 mcs pack validate .                                  # verify techpack.yaml + file refs
@@ -356,7 +395,24 @@ Anything not matching `memories/(learning|decision)_*.md` needs renaming.
 
 ---
 
-## Links
+## 🧪 Development
+
+```bash
+npm test                                             # unit, contract and behaviour suites
+npm run typecheck                                    # tsc --noEmit (deps install ad hoc in CI)
+```
+
+TypeScript run directly by Node: no build step, no runtime dependencies, no lockfile. `tsconfig.json` sets `erasableSyntaxOnly`, so the syntax stays strippable — no `enum`, no `namespace`, no constructor parameter properties.
+
+**`tests/golden/` is the behaviour contract.** Each file pins what the pack produces for one fixture: stdout, stderr, exit code, and the resulting repository state. The suite builds a throwaway project with a real git remote, installs the hooks, runs them through their shebang (pinned by `tests/manifest.test.ts` to the same command the manifest declares), and compares. A diff therefore means the pack's behaviour changed, not that a test went stale.
+
+Fixtures carry an `expect` pattern asserted against the recording, so a fixture where nothing happens fails rather than passing vacuously. Machine- and day-dependent values — temp paths, hostname, dates, git's relative timestamps — are normalised; everything else is byte-exact.
+
+CI runs on macOS across Node 22 and 24. Besides the typecheck and the suite it guards three things: the pack contains no shell at all, `hostname -s` still matches `os.hostname().split(".")[0]` (the commit subjects depend on it), and the suite leaves the working tree clean.
+
+---
+
+## 🔗 Links
 
 - [MCS](https://github.com/mcs-cli/mcs) — the configuration engine
 - [Creating Tech Packs](https://github.com/mcs-cli/mcs/blob/main/docs/creating-tech-packs.md) — guide for building your own
@@ -367,6 +423,6 @@ Anything not matching `memories/(learning|decision)_*.md` needs renaming.
 
 ---
 
-## License
+## 📄 License
 
 MIT
diff --git a/commands/approve-memories.md b/commands/approve-memories.md
index d03f1ad..083ddbf 100644
--- a/commands/approve-memories.md
+++ b/commands/approve-memories.md
@@ -14,7 +14,7 @@ Run `git -C .claude/.memories-repo status --porcelain -- memories/` and `git -C
 
 ## 2. Filename guardrail
 
-Every dirty file under `memories/` must match `^memories/(learning|decision)_[a-zA-Z0-9_-]+\.md$` — the same pattern the Stop hook enforces (keep in sync with `hooks/memories_autopush.sh` `allowed_pattern`, `hooks/memories_announce.sh` regex, and `scripts/configure-memories.sh` `allowed_pattern`). If any file fails, list the offenders, instruct the user to rename them to `memories/learning_<topic>_<specific>.md` or `memories/decision_<domain>_<topic>.md`, and stop without committing.
+Every dirty file under `memories/` must match `^memories/(learning|decision)_[a-zA-Z0-9_-]+\.md$` — the same pattern the Stop hook enforces, defined once in `runtime/lib/naming.mts`. If any file fails, list the offenders, instruct the user to rename them to `memories/learning_<topic>_<specific>.md` or `memories/decision_<domain>_<topic>.md`, and stop without committing.
 
 ## 3. Stage, commit, push
 
diff --git a/hooks/memories_announce.sh b/hooks/memories_announce.sh
deleted file mode 100755
index 5476c56..0000000
--- a/hooks/memories_announce.sh
+++ /dev/null
@@ -1,37 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-trap 'rc=$?; echo "memories_announce: aborted (rc=$rc) at line $LINENO: $BASH_COMMAND" >&2; exit 0' ERR
-
-# PostToolUse hook: surface review-mode memory writes to Claude's conversation.
-#
-# In review mode the Stop hook's pending-changes report goes to the terminal
-# only — Stop runs hookAsync: true, so its stdout never re-enters Claude's
-# context. This hook fills that gap by injecting additionalContext after a
-# memory file write, so Claude can proactively mention pending review.
-#
-# Silent in auto/full modes — those auto-push and don't need a Claude-visible
-# nudge.
-
-command -v jq >/dev/null 2>&1 || exit 0
-
-input_data=$(cat) || exit 0
-file_path=$(echo "$input_data" | jq -r '.tool_input.file_path // empty' 2>/dev/null) || exit 0
-
-# hookMatcher in techpack.yaml scopes us to Write/Edit/MultiEdit, but those
-# tools touch many paths; restrict to the exact memory-file naming convention
-# the autopush guardrail accepts. A loose glob would announce phantom pending
-# state for files autopush will silently reject (e.g. "learning_foo bar.md").
-# keep in sync with hooks/memories_autopush.sh allowed_pattern,
-# scripts/configure-memories.sh allowed_pattern, and commands/approve-memories.md guardrail
-[[ "$file_path" =~ (^|.*/)\.claude/memories/(learning|decision)_[a-zA-Z0-9_-]+\.md$ ]] || exit 0
-
-# Review mode only — auto/full/unset/unknown all auto-push and need no nudge.
-case "${MEMORIES_AUTOPUSH_MODE:-}" in
-  review) ;;
-  *)      exit 0 ;;
-esac
-
-msg="Memory file saved at $file_path (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories."
-
-jq -n --arg ctx "$msg" \
-  '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $ctx}}'
diff --git a/hooks/memories_autopush.sh b/hooks/memories_autopush.sh
deleted file mode 100755
index 89890f2..0000000
--- a/hooks/memories_autopush.sh
+++ /dev/null
@@ -1,386 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-# Hooks must never fail-fast onto Claude Code, but silent aborts are
-# undebuggable. Log the failing line/command to stderr before exiting 0.
-trap 'rc=$?; echo "memories_autopush: aborted (rc=$rc) at line $LINENO: $BASH_COMMAND" >&2; exit 0' ERR
-
-# Stop hook: handle shared-memory file changes per MEMORIES_AUTOPUSH_MODE mode.
-#
-# Modes (read from .claude/settings.local.json's `env` block — mcs writes the
-# value from the techpack prompt during `mcs sync`):
-#
-#   auto    — writes auto-pushed; deletions parked for manual review (default)
-#   full    — writes AND deletions auto-pushed
-#   review  — nothing auto; prints a per-turn pending-changes report
-#
-# In every mode, files that don't match memories/(learning_|decision_)<name>.md
-# halt everything until renamed — naming policy is orthogonal to push policy.
-# Unset, empty, or unknown values fall through to `auto`.
-#
-# After memory-audit (auto mode only) intentionally removes stale files, the
-# user approves the deletions with the pack's slash command:
-#   /approve-memories audit cleanup
-
-command -v git >/dev/null 2>&1 || { echo "memories_autopush: git not found; skipping" >&2; exit 0; }
-command -v jq  >/dev/null 2>&1 || { echo "memories_autopush: jq not found; skipping" >&2; exit 0; }
-
-input_data=$(cat) || exit 0
-echo "$input_data" | jq '.' >/dev/null 2>&1 || { echo "memories_autopush: stdin is not valid JSON; skipping" >&2; exit 0; }
-
-# Anchor on the script's own path, not stdin `cwd`. The hook ships at
-# <project>/.claude/hooks/shared-memories/<script>.sh, so the project root is
-# three `dirname` steps up. Stdin `cwd` reflects the assistant's bash session
-# pwd — `cd` drift inside a turn would otherwise hide the repo and silently
-# no-op every Stop event for the rest of the session.
-script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd) || exit 0
-project_root=$(cd -- "$script_dir/../../.." && pwd) || exit 0
-
-# Anchor on the hidden sparse checkout. Every working-tree git call below is
-# scoped with `-- memories/` so root-level repo files (README etc.) can't trip
-# the guardrail.
-memories_dir="$project_root/.claude/.memories-repo"
-if ! git -C "$memories_dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  echo "memories_autopush: $memories_dir is not a git worktree; skipping (project_root=$project_root)" >&2
-  exit 0
-fi
-
-# ── Resolve mode ─────────────────────────────────────────────────────────
-# keep in sync with hooks/memories_pull.sh mode case
-case "${MEMORIES_AUTOPUSH_MODE:-}" in
-  ""|auto) mode=auto ;;
-  full)    mode=full ;;
-  review)  mode=review ;;
-  # Unknown values fall through silently here — the SessionStart hook
-  # (memories_pull.sh) surfaces a once-per-session warning via additionalContext.
-  # Repeating it on every Stop turn was noisy and useless (the user can't fix
-  # the env without restarting the session anyway).
-  *)       mode=auto ;;
-esac
-
-# Sibling of the sparse cone (cone = memories/), so git neither tracks nor
-# pushes this file; .claude/.memories-repo is wholesale gitignored by the
-# parent project (see techpack.yaml). Only used in review mode.
-review_state_file="$memories_dir/.review-shown"
-
-# ── Fast exit if nothing to sync ─────────────────────────────────────────
-# keep in sync with hooks/memories_pull.sh uncommitted/unpushed check
-uncommitted=$(git -C "$memories_dir" status --porcelain -- memories/ 2>/dev/null | wc -l | tr -d ' ')
-unpushed=0
-if git -C "$memories_dir" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
-  unpushed=$(git -C "$memories_dir" rev-list '@{u}..HEAD' --count 2>/dev/null || echo 0)
-fi
-
-if [ "$uncommitted" -eq 0 ] && [ "$unpushed" -eq 0 ]; then
-  # Nothing pending — wipe stale review-mode state so the next change reprints
-  # fresh instead of being suppressed by a hash whose pending set is gone.
-  [ "$mode" = "review" ] && [ -f "$review_state_file" ] && rm -f "$review_state_file"
-  exit 0
-fi
-
-# Default empty so the review block sees consistent vars even when the
-# only pending state is an unpushed commit (no dirty files).
-untracked=""
-am_numstats=""
-added_modified=""
-deleted_files=""
-
-if [ "$uncommitted" -gt 0 ]; then
-  # ── Gather dirty file lists (shared by review and auto/full) ───────────
-  # keep in sync with scripts/configure-memories.sh allowed_pattern,
-  # hooks/memories_announce.sh regex, and commands/approve-memories.md guardrail
-  allowed_pattern='^memories/(learning|decision)_[a-zA-Z0-9_-]+\.md$'
-
-  untracked=$(git -C "$memories_dir" ls-files --others --exclude-standard --full-name -- memories/ 2>/dev/null || true)
-  dirty_files=$(
-    {
-      git -C "$memories_dir" diff --name-only HEAD -- memories/ 2>/dev/null || true
-      printf '%s\n' "$untracked"
-    } | grep -v '^$' | sort -u || true
-  )
-
-  # ── Filename guardrail (blocks ALL modes) ─────────────────────────────
-  bad_files=$(echo "$dirty_files" | grep -Ev "$allowed_pattern" || true)
-  if [ -n "$bad_files" ]; then
-    echo "Shared memories: skipping auto-push — unconventional filename(s):"
-    echo "$bad_files" | sed 's/^/  - /'
-    echo "Rename to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so the guardrail accepts them."
-    exit 0
-  fi
-
-  # Single --numstat call gives us both paths and per-file stats (used by the
-  # review report below). For deletions we only need names — numstat would
-  # include them with `-`/`-` stats, simpler to ask for names directly.
-  am_numstats=$(git -C "$memories_dir" diff --numstat --diff-filter=AM HEAD -- memories/ 2>/dev/null || true)
-  added_modified=$(printf '%s\n' "$am_numstats" | awk 'NF { print $3 }')
-  deleted_files=$(git -C "$memories_dir" diff --name-only --diff-filter=D HEAD -- memories/ 2>/dev/null || true)
-fi
-
-# ── Mode: review ─────────────────────────────────────────────────────────
-if [ "$mode" = "review" ]; then
-  # Build canonical pending-state string. Hash is over <status>\t<path> lines
-  # plus an UNPUSHED marker — deliberately content-agnostic, so consecutive
-  # edits with the same diff status don't trigger reprints. The report's git
-  # commands let the user inspect current content on demand.
-  state_lines=""
-  while IFS= read -r f; do
-    [ -n "$f" ] || continue
-    state_lines+="NEW	$f"$'\n'
-  done <<< "$untracked"
-  while IFS= read -r f; do
-    [ -n "$f" ] || continue
-    state_lines+="MOD	$f"$'\n'
-  done <<< "$added_modified"
-  while IFS= read -r f; do
-    [ -n "$f" ] || continue
-    state_lines+="DEL	$f"$'\n'
-  done <<< "$deleted_files"
-  if [ "$unpushed" -gt 0 ]; then
-    # If rev-parse fails the repo is degenerate (detached, mid-rebase). Skip
-    # the dedupe contribution rather than poisoning the hash with a literal —
-    # otherwise two distinct broken states would collide on the same hash.
-    head_sha=$(git -C "$memories_dir" rev-parse HEAD 2>/dev/null || true)
-    if [ -n "$head_sha" ]; then
-      state_lines+="UNPUSHED	$head_sha	$unpushed"$'\n'
-    fi
-  fi
-  # `|| true` because grep -v returns 1 on empty input (e.g. when only pending
-  # state is a renamed file: rename doesn't match AM/D filters, state_lines
-  # ends up empty, grep rc=1 + set -e + ERR trap = silent exit before our
-  # unclassified-pending fallback below can fire.
-  state_canonical=$(printf '%s' "$state_lines" | grep -v '^$' | sort || true)
-
-  if [ -z "$state_canonical" ]; then
-    # Filters captured nothing, but the fast-exit at the top of the hook
-    # confirmed at least one of uncommitted/unpushed is > 0. Possible causes:
-    # rename (R), typechange (T), conflict (UU/AA), or rev-parse HEAD failed
-    # (degenerate repo: detached, mid-rebase, corrupt refs). Print a minimal
-    # fallback so the user never sees a silent no-op when state is pending.
-    if [ "$uncommitted" -gt 0 ]; then
-      echo "Shared memories [review mode]: $uncommitted unclassified pending change(s) in memories/"
-      echo "  Inspect: git -C .claude/.memories-repo status -- memories/"
-    fi
-    if [ "$unpushed" -gt 0 ]; then
-      echo "Shared memories [review mode]: $unpushed unpushed commit(s) (HEAD unresolvable — repo may be detached or mid-rebase)"
-      echo "  Inspect: git -C .claude/.memories-repo status"
-    fi
-    exit 0
-  fi
-
-  # Dedupe: skip if the current pending set was already reported this session.
-  # SessionStart hook deletes $review_state_file once per session so an
-  # ignored report re-surfaces at the start of each new session.
-  # Hash via whatever's available — shasum (macOS), sha256sum (Linux), openssl,
-  # or git hash-object as last resort. Different algorithms produce different
-  # digests, but uniqueness within a session is all dedupe needs.
-  # Percent-encode the chars that most reliably break terminal autolink
-  # detection in file:// URLs. Spaces are the common case (project paths like
-  # "/Users/x/My Code/foo"); # and ? also break URL parsing in some terminals.
-  # Other reserved chars (parens, etc.) are passed through — most terminals
-  # tolerate them and percent-encoding everything reserved would mangle the
-  # URL beyond what the user expects to see in the report.
-  url_encode_path() {
-    local p="$1"
-    p=${p// /%20}
-    p=${p//\#/%23}
-    p=${p//\?/%3F}
-    printf '%s' "$p"
-  }
-
-  hash_stdin() {
-    if   command -v shasum    >/dev/null 2>&1; then shasum -a 256 | awk '{print $1}'
-    elif command -v sha256sum >/dev/null 2>&1; then sha256sum     | awk '{print $1}'
-    elif command -v openssl   >/dev/null 2>&1; then openssl dgst -sha256 | awk '{print $NF}'
-    else git hash-object --stdin
-    fi
-  }
-  current_hash=$(printf '%s' "$state_canonical" | hash_stdin)
-  if [ -z "$current_hash" ]; then
-    # All hashing tools failed somehow — print the report unconditionally
-    # rather than persisting an empty hash that would suppress forever.
-    echo "memories_autopush: hash tool unavailable; skipping dedupe." >&2
-  elif [ -f "$review_state_file" ]; then
-    last_hash=$(tr -d '[:space:]' < "$review_state_file" 2>/dev/null || true)
-    if [ "$current_hash" = "$last_hash" ]; then
-      exit 0
-    fi
-  fi
-
-  # Header parts — files and unpushed commits are different kinds of items, so
-  # describe them separately rather than collapsing into a single "items" count.
-  file_count=$(printf '%s\n%s\n%s\n' "$untracked" "$added_modified" "$deleted_files" | grep -cv '^$' || true)
-  # Build header without expanding an empty array — macOS Bash 3.2 + set -u
-  # treats "${parts[@]}" as unbound when parts=().
-  if [ "$file_count" -gt 0 ] && [ "$unpushed" -gt 0 ]; then
-    desc="$file_count pending file(s) in memories/ and $unpushed unpushed commit(s)"
-  elif [ "$file_count" -gt 0 ]; then
-    desc="$file_count pending file(s) in memories/"
-  else
-    desc="$unpushed unpushed commit(s)"
-  fi
-  echo "Shared memories [review mode]: $desc"
-
-  while IFS= read -r f; do
-    [ -n "$f" ] || continue
-    preview=$(grep -m1 -v '^[[:space:]]*$' "$memories_dir/$f" 2>/dev/null || true)
-    # Strip C0 control chars (incl. ESC for ANSI, BEL, CR) and DEL, but keep
-    # tab (0x09) and UTF-8 multibyte (>=0x80) so international text survives.
-    # Defends the terminal against memory files containing escape sequences.
-    preview=$(printf '%s' "$preview" | LC_ALL=C tr -d '\000-\010\013\014\016-\037\177')
-    preview=${preview:0:80}
-    echo "+ NEW  <file://$(url_encode_path "$memories_dir/$f")>"
-    [ -n "$preview" ] && echo "       \"$preview\""
-  done <<< "$untracked"
-
-  # Stats batched into am_numstats above — no per-file git invocation here.
-  while IFS=$'\t' read -r added deleted f; do
-    [ -n "$f" ] || continue
-    echo "~ MOD  <file://$(url_encode_path "$memories_dir/$f")>  (+$added -$deleted)"
-    echo "       Diff: git -C .claude/.memories-repo diff -- $f"
-  done <<< "$am_numstats"
-
-  # Per-file `git log` is one process per deletion. For typical deletions
-  # (1–5 files) the cost is negligible; for large memory-audit runs we cap
-  # the timestamp lookups so latency stays predictable.
-  del_idx=0
-  while IFS= read -r f; do
-    [ -n "$f" ] || continue
-    del_idx=$((del_idx + 1))
-    if [ "$del_idx" -le 20 ]; then
-      last=$(git -C "$memories_dir" log -1 --format=%cr HEAD -- "$f" 2>/dev/null || echo "?")
-      echo "- DEL  $f  (last modified $last)"
-    else
-      echo "- DEL  $f"
-    fi
-    echo "       Recover: git -C .claude/.memories-repo checkout HEAD -- $f"
-  done <<< "$deleted_files"
-
-  echo ""
-  if [ "$unpushed" -gt 0 ]; then
-    echo "  Note: $unpushed local commit(s) not yet on the remote."
-    echo "        Push: git -C .claude/.memories-repo pull --rebase --autostash && git -C .claude/.memories-repo push"
-    echo ""
-  fi
-  echo "Approve all:           /approve-memories  [optional commit reason]"
-  echo "Discard local changes: git -C .claude/.memories-repo checkout -- memories/ \\"
-  echo "                       && git -C .claude/.memories-repo clean -f -- memories/"
-
-  if [ -n "$current_hash" ]; then
-    # Atomic write so a killed hook can't leave an empty state file behind.
-    printf '%s\n' "$current_hash" > "$review_state_file.tmp" \
-      && mv "$review_state_file.tmp" "$review_state_file"
-  fi
-  exit 0
-fi
-
-# ── Modes: auto / full ───────────────────────────────────────────────────
-committed=0
-
-if [ "$uncommitted" -gt 0 ]; then
-  if [ "$mode" = "auto" ]; then
-    if [ -n "$deleted_files" ]; then
-      del_count=$(echo "$deleted_files" | wc -l | tr -d ' ')
-      echo "Shared memories: $del_count deleted memory file(s) left for manual review (not auto-pushed):"
-      echo "$deleted_files" | sed 's/^/  - /'
-      echo "If intentional (e.g. after memory-audit), approve them:"
-      echo "  /approve-memories audit cleanup"
-    fi
-
-    # Stage adds/mods only — deletions stay in the working tree.
-    stageable=$(
-      {
-        printf '%s\n' "$added_modified"
-        printf '%s\n' "$untracked"
-      } | grep -v '^$' | sort -u || true
-    )
-
-    if [ -n "$stageable" ]; then
-      while IFS= read -r f; do
-        [ -n "$f" ] || continue
-        git -C "$memories_dir" add -- "$f"
-      done <<< "$stageable"
-    fi
-  else
-    git -C "$memories_dir" add -A -- memories/
-  fi
-
-  if ! git -C "$memories_dir" diff --cached --quiet -- memories/ 2>/dev/null; then
-    host=$(hostname -s)
-    date_str=$(date +%F)
-    if [ "$mode" = "full" ] && [ -n "$deleted_files" ]; then
-      msg="auto: memories from $host $date_str (includes deletions)"
-    else
-      msg="auto: memories from $host $date_str"
-    fi
-    if commit_err=$(git -C "$memories_dir" commit -m "$msg" --quiet 2>&1); then
-      committed=1
-    else
-      echo "Shared memories: commit failed; will retry on next Stop."
-      [ -n "$commit_err" ] && printf '  %s\n' "$commit_err"
-      exit 0
-    fi
-  fi
-fi
-
-# Re-check unpushed only if we just committed — HEAD didn't move otherwise.
-if [ "$committed" -eq 1 ]; then
-  unpushed=0
-  if git -C "$memories_dir" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
-    unpushed=$(git -C "$memories_dir" rev-list '@{u}..HEAD' --count 2>/dev/null || echo 0)
-  fi
-fi
-[ "$unpushed" -eq 0 ] && exit 0
-
-# Stop hooks fire at turn boundaries, so a team pushes to one branch at the same
-# instant and a single attempt lands exactly one writer.
-push_attempts=${MEMORIES_PUSH_ATTEMPTS:-12}
-# A non-integer would error in the numeric test below and hit the ERR trap.
-case "$push_attempts" in
-  ''|*[!0-9]*) push_attempts=12 ;;
-  0)           push_attempts=1  ;;
-esac
-attempt=1
-while :; do
-if ! pull_err=$(LC_ALL=C git -C "$memories_dir" pull --rebase --autostash --quiet 2>&1); then
-  # Distinguish actual rebase conflicts from network/auth/etc. so the message
-  # matches reality. LC_ALL=C above forces English git output so the CONFLICT
-  # marker is stable — without it, French/German/Japanese locales emit
-  # CONFLIT/KONFLIKT/衝突 and the grep would misclassify the failure.
-  if printf '%s' "$pull_err" | grep -qi 'conflict'; then
-    if ! abort_err=$(git -C "$memories_dir" rebase --abort 2>&1); then
-      echo "Shared memories: rebase conflict AND --abort failed — repo may be in a half-rebased state. Resolve manually in .claude/.memories-repo/memories."
-      [ -n "$abort_err" ] && printf '  %s\n' "$abort_err"
-    else
-      echo "Shared memories: auto-push paused — rebase conflict. Resolve manually in .claude/.memories-repo/memories."
-    fi
-  else
-    echo "Shared memories: pull --rebase failed (likely auth or network). Will retry on next Stop."
-    [ -n "$pull_err" ] && printf '  %s\n' "$pull_err"
-  fi
-  exit 0
-fi
-
-if push_err=$(git -C "$memories_dir" push --quiet 2>&1); then
-  break
-else
-  push_rc=$?
-fi
-
-if [ "$push_rc" -ne 1 ]; then
-  echo "Shared memories: auto-push failed (not a rejected update — auth, network or repository). Will retry on next Stop."
-  [ -n "$push_err" ] && printf '  %s\n' "$push_err"
-  break
-fi
-
-if [ "$attempt" -ge "$push_attempts" ]; then
-  echo "Shared memories: auto-push failed after $attempt attempt(s). Will retry on next Stop."
-  [ -n "$push_err" ] && printf '  %s\n' "$push_err"
-  break
-fi
-
-# Full jitter, capped at 1.5s. Seeded explicitly because awk's srand() reads the
-# clock at one-second resolution — writers colliding in the same second would
-# otherwise draw identical delays and wake together.
-jitter_seed=$(( ${RANDOM:-0} ^ $$ ^ attempt ))
-sleep "$(awk -v a="$attempt" -v seed="$jitter_seed" 'BEGIN{srand(seed);d=0.05*(2^a);if(d>1.5)d=1.5;printf "%.3f", rand()*d}')"
-attempt=$((attempt+1))
-done
diff --git a/hooks/memories_pull.sh b/hooks/memories_pull.sh
deleted file mode 100755
index 6162b9c..0000000
--- a/hooks/memories_pull.sh
+++ /dev/null
@@ -1,96 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-trap 'rc=$?; echo "memories_pull: aborted (rc=$rc) at line $LINENO: $BASH_COMMAND" >&2; exit 0' ERR
-
-# SessionStart hook: fast-forward shared memories and surface any state left
-# behind by a previous Stop hook's auto-push (auth failure, rebase conflict,
-# guardrail refusal). This is the safety net that keeps silent push failures
-# from accumulating invisibly.
-
-command -v git >/dev/null 2>&1 || { echo "memories_pull: git not found; skipping" >&2; exit 0; }
-command -v jq  >/dev/null 2>&1 || { echo "memories_pull: jq not found; skipping" >&2; exit 0; }
-
-input_data=$(cat) || exit 0
-echo "$input_data" | jq '.' >/dev/null 2>&1 || { echo "memories_pull: stdin is not valid JSON; skipping" >&2; exit 0; }
-
-# Anchor on the script's own path, not stdin `cwd`. The hook ships at
-# <project>/.claude/hooks/shared-memories/<script>.sh, so the project root is
-# three `dirname` steps up. Script-relative anchoring keeps us cwd-agnostic
-# and matches memories_autopush.sh's resolution.
-script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd) || exit 0
-project_root=$(cd -- "$script_dir/../../.." && pwd) || exit 0
-
-# Anchor on the hidden sparse checkout (the git work tree) rather than the
-# .claude/memories symlink — same git root, but one less level of indirection.
-memories_dir="$project_root/.claude/.memories-repo"
-if ! git -C "$memories_dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  echo "memories_pull: $memories_dir is not a git worktree; skipping (project_root=$project_root)" >&2
-  exit 0
-fi
-
-# keep in sync with hooks/memories_autopush.sh mode case
-# Unknown values surface a one-time warning via additionalContext below
-# (echo here would be swallowed — SessionStart hooks only speak to Claude
-# through the JSON channel). Once-per-session beats every-turn noise.
-mode_warning=""
-case "${MEMORIES_AUTOPUSH_MODE:-}" in
-  ""|auto) mode=auto ;;
-  full)    mode=full ;;
-  review)  mode=review ;;
-  *)       mode=auto
-           mode_warning="Shared memories: unknown MEMORIES_AUTOPUSH_MODE='${MEMORIES_AUTOPUSH_MODE}' — falling back to auto. Fix the value in .claude/settings.local.json (valid: auto, full, review) and restart the session." ;;
-esac
-
-# Fast-forward; ignore errors (covered by the state check below).
-git -C "$memories_dir" pull --ff-only --quiet >/dev/null 2>&1 || true
-
-# In review mode, reset the Stop hook's dedupe state once per session so any
-# pending changes the user previously ignored re-surface in the new session.
-# Without this reset, an unresolved review report would stay silent forever
-# after its hash settled. The state file lives outside the sparse cone, so
-# git ignores it and there's nothing to clean up beyond the rm.
-if [ "$mode" = "review" ]; then
-  # keep in sync with hooks/memories_autopush.sh review_state_file path
-  rm -f "$memories_dir/.review-shown" 2>/dev/null || true
-fi
-
-# Detect lingering state: uncommitted memory files OR local ahead of upstream.
-# keep in sync with hooks/memories_autopush.sh uncommitted/unpushed check
-uncommitted=$(git -C "$memories_dir" status --porcelain -- memories/ 2>/dev/null | wc -l | tr -d ' ')
-unpushed=0
-if git -C "$memories_dir" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
-  unpushed=$(git -C "$memories_dir" rev-list '@{u}..HEAD' --count 2>/dev/null || echo 0)
-fi
-
-# Build pending-state message if any. Without pending state, we still emit
-# the additionalContext when there's a mode_warning to surface.
-pending_msg=""
-if [ "$uncommitted" -gt 0 ] || [ "$unpushed" -gt 0 ]; then
-  if [ "$uncommitted" -gt 0 ] && [ "$unpushed" -gt 0 ]; then
-    joined="$uncommitted uncommitted file(s), $unpushed unpushed commit(s)"
-  elif [ "$uncommitted" -gt 0 ]; then
-    joined="$uncommitted uncommitted file(s)"
-  else
-    joined="$unpushed unpushed commit(s)"
-  fi
-  if [ "$mode" = "review" ]; then
-    pending_msg="Shared memories: ${joined} awaiting review (MEMORIES_AUTOPUSH_MODE=review). End a turn to see the per-file report with approve/discard commands."
-  else
-    pending_msg="Shared memories have lingering state: ${joined}. The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically."
-  fi
-fi
-
-# Combine warning and pending into one additionalContext payload, or exit
-# silently if neither is present.
-if [ -n "$mode_warning" ] && [ -n "$pending_msg" ]; then
-  msg="$mode_warning"$'\n\n'"$pending_msg"
-elif [ -n "$mode_warning" ]; then
-  msg="$mode_warning"
-elif [ -n "$pending_msg" ]; then
-  msg="$pending_msg"
-else
-  exit 0
-fi
-
-jq -n --arg ctx "$msg" \
-  '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..d2a2367
--- /dev/null
+++ b/package.json
@@ -0,0 +1,12 @@
+{
+  "private": true,
+  "type": "module",
+  "description": "Hook and script sources for the shared-memories techpack. Zero runtime dependencies; run by `node --experimental-strip-types`. Typecheck deps install ad hoc in CI.",
+  "engines": {
+    "node": ">=22.6"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --test \"tests/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
+  }
+}
diff --git a/runtime/announce.mts b/runtime/announce.mts
new file mode 100755
index 0000000..119ee14
--- /dev/null
+++ b/runtime/announce.mts
@@ -0,0 +1,58 @@
+#!/usr/bin/env -S node --experimental-strip-types --disable-warning=ExperimentalWarning
+import { additionalContext, failOpen, readStdin, streamValues } from "./lib/hook-io.mts";
+import { MEMORY_WRITE_PATTERN } from "./lib/naming.mts";
+
+const isObject = (v: unknown): v is Record<string, unknown> =>
+	typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** How `jq -r` renders one result: strings raw, everything else as pretty JSON. */
+const render = (v: unknown): string => (typeof v === "string" ? v : JSON.stringify(v, null, 2));
+
+/**
+ * `jq -r '.tool_input.file_path // empty'` over every value on stdin, joined by
+ * newlines. jq does not stop at an erroring value — it skips it and carries on —
+ * and its exit status reflects only the LAST value. The bash's `|| exit 0` therefore
+ * fires only when the final value errored, which is what null means here.
+ */
+function filePaths(values: readonly unknown[]): string | null {
+	const out: string[] = [];
+	let lastErrored = false;
+	for (const value of values) {
+		lastErrored = false;
+
+		let toolInput: unknown = null;
+		if (isObject(value)) toolInput = value["tool_input"] ?? null;
+		else if (value !== null) {
+			lastErrored = true;
+			continue;
+		}
+
+		let filePath: unknown = null;
+		if (isObject(toolInput)) filePath = toolInput["file_path"] ?? null;
+		else if (toolInput !== null) {
+			lastErrored = true;
+			continue;
+		}
+
+		if (filePath === null || filePath === false) continue;
+		out.push(render(filePath));
+	}
+	// `$(...)` strips trailing newlines, and jq emits one per result.
+	return lastErrored ? null : out.join("\n").replace(/\n+$/, "");
+}
+
+failOpen("memories_announce", () => {
+	const values = streamValues(readStdin());
+	if (values === null) return;
+
+	const filePath = filePaths(values);
+	if (filePath === null || !MEMORY_WRITE_PATTERN.test(filePath)) return;
+
+	// The bash matches the literal, not the resolved mode: unknown values are silent here.
+	if (process.env["MEMORIES_AUTOPUSH_MODE"] !== "review") return;
+
+	additionalContext(
+		"PostToolUse",
+		`Memory file saved at ${filePath} (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.`,
+	);
+});
diff --git a/runtime/autopush.mts b/runtime/autopush.mts
new file mode 100755
index 0000000..95c164d
--- /dev/null
+++ b/runtime/autopush.mts
@@ -0,0 +1,124 @@
+#!/usr/bin/env -S node --experimental-strip-types --disable-warning=ExperimentalWarning
+import { existsSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { git, gitPresent, isWorkTree, unpushedCount } from "./lib/git.mts";
+import { failOpen, isJsonStream, readStdin, say, warn } from "./lib/hook-io.mts";
+import { resolveMode } from "./lib/mode.mts";
+import { badNames, collect, headSha, modifiedPaths, uncommittedCount } from "./lib/pending.mts";
+import { memoriesRepo, projectRoot } from "./lib/paths.mts";
+import { RENAME_HINT } from "./lib/naming.mts";
+import { canonicalState, hashState, lastShownHash, renderReport } from "./lib/report.mts";
+import { syncToRemote } from "./lib/push.mts";
+
+const NAME = "memories_autopush";
+
+/** A failed stage must not read as "nothing to commit"; let git speak and abort the turn. */
+const stage = (repo: string, args: readonly string[]): void => {
+	const r = git(repo, args, { inheritStderr: true });
+	if (!r.ok) throw new Error(`git ${args.join(" ")} failed (exit ${r.exit ?? r.failure})`);
+};
+
+const today = (): string => {
+	const d = new Date();
+	const p = (n: number) => String(n).padStart(2, "0");
+	return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+};
+
+failOpen(NAME, () => {
+	if (!gitPresent()) return warn(`${NAME}: git not found; skipping`);
+	if (!isJsonStream(readStdin())) return warn(`${NAME}: stdin is not valid JSON; skipping`);
+
+	const project = projectRoot(import.meta.dirname);
+	const repo = memoriesRepo(project);
+	if (!isWorkTree(repo)) {
+		return warn(`${NAME}: ${repo} is not a git worktree; skipping (project_root=${project})`);
+	}
+
+	const { mode } = resolveMode(process.env["MEMORIES_AUTOPUSH_MODE"]);
+	const reviewState = join(repo, ".review-shown");
+
+	const uncommitted = uncommittedCount(repo);
+	let unpushed = unpushedCount(repo);
+
+	if (uncommitted === 0 && unpushed === 0) {
+		if (mode === "review" && existsSync(reviewState)) rmSync(reviewState, { force: true });
+		return;
+	}
+
+	const pending = collect(repo, uncommitted, unpushed);
+
+	if (uncommitted > 0) {
+		const bad = badNames(repo, pending.untracked);
+		if (bad.length > 0) {
+			say("Shared memories: skipping auto-push — unconventional filename(s):");
+			for (const f of bad) say(`  - ${f}`);
+			say(RENAME_HINT);
+			return;
+		}
+	}
+
+	if (mode === "review") {
+		const state = canonicalState(pending, pending.unpushed > 0 ? headSha(repo) : "");
+		if (state === "") {
+			// Renames, typechanges, conflicts, or an unresolvable HEAD reach none of the filters.
+			if (uncommitted > 0) {
+				say(`Shared memories [review mode]: ${uncommitted} unclassified pending change(s) in memories/`);
+				say("  Inspect: git -C .claude/.memories-repo status -- memories/");
+			}
+			if (unpushed > 0) {
+				say(
+					`Shared memories [review mode]: ${unpushed} unpushed commit(s) (HEAD unresolvable — repo may be detached or mid-rebase)`,
+				);
+				say("  Inspect: git -C .claude/.memories-repo status");
+			}
+			return;
+		}
+
+		const hash = hashState(state);
+		if (lastShownHash(reviewState) === hash) return;
+
+		for (const line of renderReport(repo, pending)) say(line);
+
+		// Atomic, so a killed hook cannot leave an empty state file behind.
+		writeFileSync(`${reviewState}.tmp`, `${hash}\n`);
+		renameSync(`${reviewState}.tmp`, reviewState);
+		return;
+	}
+
+	let committed = false;
+
+	if (uncommitted > 0) {
+		if (mode === "auto") {
+			if (pending.deleted.length > 0) {
+				say(`Shared memories: ${pending.deleted.length} deleted memory file(s) left for manual review (not auto-pushed):`);
+				for (const f of pending.deleted) say(`  - ${f}`);
+				say("If intentional (e.g. after memory-audit), approve them:");
+				say("  /approve-memories audit cleanup");
+			}
+			const stageable = [...new Set([...modifiedPaths(pending), ...pending.untracked])].filter(Boolean).sort();
+			for (const f of stageable) stage(repo, ["add", "--", f]);
+		} else {
+			stage(repo, ["add", "-A", "--", "memories/"]);
+		}
+
+		if (!git(repo, ["diff", "--cached", "--quiet", "--", "memories/"]).ok) {
+			const suffix = mode === "full" && pending.deleted.length > 0 ? " (includes deletions)" : "";
+			const msg = `auto: memories from ${hostname().split(".")[0]} ${today()}${suffix}`;
+			const commit = git(repo, ["commit", "-m", msg, "--quiet"]);
+			if (commit.ok) {
+				committed = true;
+			} else {
+				say("Shared memories: commit failed; will retry on next Stop.");
+				const err = `${commit.stdout}${commit.stderr}`.replace(/\n$/, "");
+				if (err !== "") process.stdout.write(`  ${err}\n`);
+				return;
+			}
+		}
+	}
+
+	if (committed) unpushed = unpushedCount(repo);
+	if (unpushed === 0) return;
+
+	syncToRemote(repo, process.env["MEMORIES_PUSH_ATTEMPTS"]);
+});
diff --git a/runtime/lib/git.mts b/runtime/lib/git.mts
new file mode 100644
index 0000000..d81ac2d
--- /dev/null
+++ b/runtime/lib/git.mts
@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+
+export type GitRun = {
+	readonly ok: boolean;
+	readonly stdout: string;
+	readonly stderr: string;
+	/** The process's own exit status, or null when it never produced one. */
+	readonly exit: number | null;
+	/** Why there is no status: an errno if it never started, or the signal that killed it. */
+	readonly failure: string | null;
+};
+
+export type GitOpts = {
+	readonly env?: Readonly<Record<string, string>>;
+	/** For calls the bash leaves unredirected, so git's own progress still reaches the user. */
+	readonly inheritStderr?: boolean;
+};
+
+export function git(cwd: string, args: readonly string[], opts: GitOpts = {}): GitRun {
+	const r = spawnSync("git", ["-C", cwd, ...args], {
+		encoding: "utf8",
+		// `$(git ...)` was bounded only by memory. spawnSync defaults to 1MB, then
+		// kills git with ENOBUFS, which `gitOut` turns into "" — a large enough
+		// `status --porcelain` would read as "nothing pending".
+		maxBuffer: Infinity,
+		stdio: ["ignore", "pipe", opts.inheritStderr === true ? "inherit" : "pipe"],
+		env: opts.env ? { ...process.env, ...opts.env } : process.env,
+	});
+	const errno = (r.error as NodeJS.ErrnoException | undefined)?.code;
+	return {
+		ok: r.status === 0,
+		stdout: r.stdout ?? "",
+		stderr: r.stderr ?? "",
+		exit: r.status ?? null,
+		failure: errno ?? r.signal ?? null,
+	};
+}
+
+/** stdout trimmed, or "" on any failure — the `$(... || true)` shape. */
+export function gitOut(cwd: string, args: readonly string[]): string {
+	return git(cwd, args).stdout.trim();
+}
+
+export function gitLines(cwd: string, args: readonly string[]): string[] {
+	return git(cwd, args)
+		.stdout.split("\n")
+		.filter((l) => l !== "");
+}
+
+export function isWorkTree(dir: string): boolean {
+	return git(dir, ["rev-parse", "--is-inside-work-tree"]).ok;
+}
+
+export function hasUpstream(dir: string): boolean {
+	return git(dir, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]).ok;
+}
+
+export function unpushedCount(dir: string): number {
+	if (!hasUpstream(dir)) return 0;
+	const out = gitOut(dir, ["rev-list", "@{u}..HEAD", "--count"]);
+	const n = Number.parseInt(out, 10);
+	return Number.isNaN(n) ? 0 : n;
+}
+
+/** Whether the binary exists, the question `command -v git` asked. */
+export function gitPresent(): boolean {
+	const r = spawnSync("git", ["--version"], { stdio: "ignore" });
+	return (r.error as NodeJS.ErrnoException | undefined)?.code !== "ENOENT";
+}
diff --git a/runtime/lib/hook-io.mts b/runtime/lib/hook-io.mts
new file mode 100644
index 0000000..8059e95
--- /dev/null
+++ b/runtime/lib/hook-io.mts
@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+
+export function readStdin(): string {
+	try {
+		return readFileSync(0, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+export function parseJson(raw: string): unknown {
+	try {
+		return JSON.parse(raw) as unknown;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Matches `jq -n` output: two-space indent, trailing newline. */
+export function emitJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function additionalContext(hookEventName: string, ctx: string): void {
+	emitJson({ hookSpecificOutput: { hookEventName, additionalContext: ctx } });
+}
+
+export function say(line: string): void {
+	process.stdout.write(`${line}\n`);
+}
+
+export function warn(line: string): void {
+	process.stderr.write(`${line}\n`);
+}
+
+/**
+ * The ERR-trap contract: nothing escapes, the hook always exits 0.
+ * `exitCode` rather than `exit()`, which does not wait for an async pipe write
+ * and can truncate a long review report.
+ */
+export function failOpen(name: string, body: () => void): void {
+	// A reader that goes away is not the hook's failure. Node raises EPIPE as an
+	// asynchronous `error` event on the stream rather than at the write, so the
+	// catch below cannot see it, and the default handler prints a stack trace and
+	// exits non-zero — precisely what this contract rules out.
+	process.stdout.on("error", () => {});
+	process.stderr.on("error", () => {});
+	try {
+		body();
+	} catch (e) {
+		const detail = e instanceof Error ? e.message : String(e);
+		try {
+			process.stderr.write(`${name}: aborted — ${detail}\n`);
+		} catch {
+			// Nowhere left to report to; exiting 0 still holds.
+		}
+	}
+	process.exitCode = 0;
+}
+
+const NUMBER = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/;
+const LITERAL = /^(true|false|null)/;
+
+function scanValue(s: string, start: number): number {
+	const c = s[start];
+	if (c === "{" || c === "[") {
+		const close = c === "{" ? "}" : "]";
+		let depth = 0;
+		for (let i = start; i < s.length; i++) {
+			const ch = s[i];
+			if (ch === '"') {
+				i = scanString(s, i) - 1;
+				if (i < start) return -1;
+				continue;
+			}
+			if (ch === c) depth++;
+			else if (ch === close && --depth === 0) return i + 1;
+		}
+		return -1;
+	}
+	if (c === '"') return scanString(s, start);
+	const rest = s.slice(start);
+	const lit = LITERAL.exec(rest);
+	if (lit) return start + lit[0].length;
+	const num = NUMBER.exec(rest);
+	if (num) return start + num[0].length;
+	return -1;
+}
+
+function scanString(s: string, start: number): number {
+	for (let i = start + 1; i < s.length; i++) {
+		if (s[i] === "\\") i++;
+		else if (s[i] === '"') return i + 1;
+	}
+	return -1;
+}
+
+/**
+ * The values `jq` would read from stdin, or null if it would have failed.
+ * jq is a STREAM parser: empty input and several whitespace-separated values
+ * are both valid, and JSON.parse rejects both. Used as a validity gate, the
+ * difference decides whether a hook does its work at all.
+ */
+export function streamValues(raw: string): unknown[] | null {
+	const values: unknown[] = [];
+	let i = 0;
+	while (i < raw.length) {
+		while (i < raw.length && /\s/.test(raw[i] ?? "")) i++;
+		if (i >= raw.length) break;
+		const end = scanValue(raw, i);
+		if (end < 0) return null;
+		try {
+			values.push(JSON.parse(raw.slice(i, end)));
+		} catch {
+			return null;
+		}
+		i = end;
+	}
+	return values;
+}
+
+export function isJsonStream(raw: string): boolean {
+	return streamValues(raw) !== null;
+}
diff --git a/runtime/lib/mode.mts b/runtime/lib/mode.mts
new file mode 100644
index 0000000..9de9190
--- /dev/null
+++ b/runtime/lib/mode.mts
@@ -0,0 +1,21 @@
+export const MODES = ["auto", "full", "review"] as const;
+export type Mode = (typeof MODES)[number];
+
+export type ModeResult =
+	| { readonly mode: Mode; readonly unrecognised: null }
+	| { readonly mode: "auto"; readonly unrecognised: string };
+
+export function resolveMode(raw: string | undefined): ModeResult {
+	switch (raw) {
+		case undefined:
+		case "":
+		case "auto":
+			return { mode: "auto", unrecognised: null };
+		case "full":
+			return { mode: "full", unrecognised: null };
+		case "review":
+			return { mode: "review", unrecognised: null };
+		default:
+			return { mode: "auto", unrecognised: raw };
+	}
+}
diff --git a/runtime/lib/naming.mts b/runtime/lib/naming.mts
new file mode 100644
index 0000000..ffde79d
--- /dev/null
+++ b/runtime/lib/naming.mts
@@ -0,0 +1,7 @@
+/** The one definition. Bash carried four copies kept in step by comment. */
+export const ALLOWED_PATTERN = /^memories\/(learning|decision)_[a-zA-Z0-9_-]+\.md$/;
+
+export const MEMORY_WRITE_PATTERN = /(^|.*\/)\.claude\/memories\/(learning|decision)_[a-zA-Z0-9_-]+\.md$/;
+
+export const RENAME_HINT =
+	"Rename to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so the guardrail accepts them.";
diff --git a/runtime/lib/paths.mts b/runtime/lib/paths.mts
new file mode 100644
index 0000000..dcf991c
--- /dev/null
+++ b/runtime/lib/paths.mts
@@ -0,0 +1,10 @@
+import { resolve } from "node:path";
+
+/** Entries live at <project>/.claude/hooks/<pack-id>/, three levels down. */
+export function projectRoot(hookDir: string): string {
+	return resolve(hookDir, "..", "..", "..");
+}
+
+export function memoriesRepo(project: string): string {
+	return resolve(project, ".claude", ".memories-repo");
+}
diff --git a/runtime/lib/pending.mts b/runtime/lib/pending.mts
new file mode 100644
index 0000000..98ebc9a
--- /dev/null
+++ b/runtime/lib/pending.mts
@@ -0,0 +1,52 @@
+import { gitLines, gitOut, unpushedCount } from "./git.mts";
+import { ALLOWED_PATTERN } from "./naming.mts";
+
+export type NumStat = { readonly added: string; readonly deleted: string; readonly path: string };
+
+export type Pending = {
+	readonly uncommitted: number;
+	readonly unpushed: number;
+	readonly untracked: readonly string[];
+	readonly numstats: readonly NumStat[];
+	readonly deleted: readonly string[];
+};
+
+/** The paths `git diff --numstat --diff-filter=AM` reported, derived rather than stored. */
+export const modifiedPaths = (p: Pending): string[] => p.numstats.map((n) => n.path).filter(Boolean);
+
+export function uncommittedCount(repo: string): number {
+	return gitLines(repo, ["status", "--porcelain", "--", "memories/"]).length;
+}
+
+export function collect(repo: string, uncommitted: number, unpushed: number): Pending {
+	if (uncommitted === 0) {
+		return { uncommitted, unpushed, untracked: [], numstats: [], deleted: [] };
+	}
+	const untracked = gitLines(repo, ["ls-files", "--others", "--exclude-standard", "--full-name", "--", "memories/"]);
+	const numstats = gitLines(repo, ["diff", "--numstat", "--diff-filter=AM", "HEAD", "--", "memories/"])
+		.map((l) => l.split("\t"))
+		.filter((p): p is [string, string, string] => p.length === 3)
+		.map(([added, deleted, path]) => ({ added, deleted, path }));
+	return {
+		uncommitted,
+		unpushed,
+		untracked,
+		numstats,
+		deleted: gitLines(repo, ["diff", "--name-only", "--diff-filter=D", "HEAD", "--", "memories/"]),
+	};
+}
+
+/** `{ diff --name-only HEAD ; untracked } | sort -u`, then the guardrail. */
+export function badNames(repo: string, untracked: readonly string[]): string[] {
+	const tracked = gitLines(repo, ["diff", "--name-only", "HEAD", "--", "memories/"]);
+	const dirty = [...new Set([...tracked, ...untracked])].filter((f) => f !== "").sort();
+	return dirty.filter((f) => !ALLOWED_PATTERN.test(f));
+}
+
+export function recountUnpushed(repo: string): number {
+	return unpushedCount(repo);
+}
+
+export function headSha(repo: string): string {
+	return gitOut(repo, ["rev-parse", "HEAD"]);
+}
diff --git a/runtime/lib/push.mts b/runtime/lib/push.mts
new file mode 100644
index 0000000..cfe3844
--- /dev/null
+++ b/runtime/lib/push.mts
@@ -0,0 +1,69 @@
+import { git } from "./git.mts";
+import { say } from "./hook-io.mts";
+
+export function pushAttempts(raw: string | undefined): number {
+	if (raw === undefined || raw === "") return 12;
+	if (!/^\d+$/.test(raw)) return 12;
+	const n = Number.parseInt(raw, 10);
+	return n === 0 ? 1 : n;
+}
+
+/** Full jitter, capped at 1.5s, matching the bash `0.05 * 2^attempt` schedule. */
+export function jitterMs(attempt: number, random = Math.random): number {
+	const ceiling = Math.min(0.05 * 2 ** attempt, 1.5);
+	return Math.round(random() * ceiling * 1000);
+}
+
+/** Synchronous: the hook must finish before the turn proceeds. */
+function sleep(ms: number): void {
+	if (ms <= 0) return;
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** `printf '  %s\n' "$err"` indents the first line only. */
+function detail(err: string): void {
+	if (err !== "") process.stdout.write(`  ${err}\n`);
+}
+
+export function syncToRemote(repo: string, attemptsRaw: string | undefined): void {
+	const attempts = pushAttempts(attemptsRaw);
+	for (let attempt = 1; ; attempt++) {
+		// LC_ALL=C pins git's language so the conflict match survives a non-English locale.
+		const pull = git(repo, ["pull", "--rebase", "--autostash", "--quiet"], { env: { LC_ALL: "C" } });
+		if (!pull.ok) {
+			const err = pull.stderr.replace(/\n$/, "");
+			if (/conflict/i.test(err)) {
+				const abort = git(repo, ["rebase", "--abort"]);
+				if (!abort.ok) {
+					say(
+						"Shared memories: rebase conflict AND --abort failed — repo may be in a half-rebased state. Resolve manually in .claude/.memories-repo/memories.",
+					);
+					detail(abort.stderr.replace(/\n$/, ""));
+				} else {
+					say("Shared memories: auto-push paused — rebase conflict. Resolve manually in .claude/.memories-repo/memories.");
+				}
+			} else {
+				say("Shared memories: pull --rebase failed (likely auth or network). Will retry on next Stop.");
+				detail(err);
+			}
+			return;
+		}
+
+		const push = git(repo, ["push", "--quiet"]);
+		if (push.ok) return;
+		const err = push.stderr.replace(/\n$/, "");
+
+		// Exit code, not message text: only 1 means the remote rejected the update.
+		if (push.exit !== 1) {
+			say("Shared memories: auto-push failed (not a rejected update — auth, network or repository). Will retry on next Stop.");
+			detail(err);
+			return;
+		}
+		if (attempt >= attempts) {
+			say(`Shared memories: auto-push failed after ${attempt} attempt(s). Will retry on next Stop.`);
+			detail(err);
+			return;
+		}
+		sleep(jitterMs(attempt));
+	}
+}
diff --git a/runtime/lib/report.mts b/runtime/lib/report.mts
new file mode 100644
index 0000000..9774c78
--- /dev/null
+++ b/runtime/lib/report.mts
@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gitOut } from "./git.mts";
+import { modifiedPaths, type Pending } from "./pending.mts";
+
+/** Only these three break terminal autolinking of file:// URLs; the bash leaves the rest. */
+export function urlEncodePath(p: string): string {
+	return p.replaceAll(" ", "%20").replaceAll("#", "%23").replaceAll("?", "%3F");
+}
+
+/** `tr -d '\000-\010\013\014\016-\037\177'`. Tab, LF and CR are deliberately NOT in that set. */
+const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+
+export function preview(repo: string, file: string): string {
+	let text: string;
+	try {
+		text = readFileSync(join(repo, file), "utf8");
+	} catch {
+		return "";
+	}
+	// grep's [[:space:]] includes CR, so a CRLF file's blank line is blank here too.
+	const first = text.split("\n").find((l) => !/^[\t\n\v\f\r ]*$/.test(l)) ?? "";
+	// bash ${var:0:80} counts characters, so an astral char is one, not two.
+	return Array.from(first.replace(CONTROL, "")).slice(0, 80).join("");
+}
+
+/**
+ * The hash the last review printed, or "" when it cannot be read.
+ * The bash was `tr -d '[:space:]' < "$f" 2>/dev/null || true`, so an unreadable
+ * state file meant no dedupe rather than no report. Reading it is racy besides:
+ * a concurrent session's Stop hook can remove it between the check and the read,
+ * and losing the whole report to that is the one outcome this pack avoids.
+ */
+export function lastShownHash(stateFile: string): string {
+	try {
+		return readFileSync(stateFile, "utf8").replace(/\s/g, "");
+	} catch {
+		return "";
+	}
+}
+
+export function canonicalState(p: Pending, headSha: string): string {
+	const lines = [
+		...p.untracked.filter(Boolean).map((f) => `NEW\t${f}`),
+		...modifiedPaths(p).map((f) => `MOD\t${f}`),
+		...p.deleted.filter(Boolean).map((f) => `DEL\t${f}`),
+	];
+	if (p.unpushed > 0 && headSha !== "") lines.push(`UNPUSHED\t${headSha}\t${p.unpushed}`);
+	return lines.sort().join("\n");
+}
+
+export function hashState(state: string): string {
+	return createHash("sha256").update(state).digest("hex");
+}
+
+export function describe(fileCount: number, unpushed: number): string {
+	if (fileCount > 0 && unpushed > 0) {
+		return `${fileCount} pending file(s) in memories/ and ${unpushed} unpushed commit(s)`;
+	}
+	if (fileCount > 0) return `${fileCount} pending file(s) in memories/`;
+	return `${unpushed} unpushed commit(s)`;
+}
+
+export function renderReport(repo: string, p: Pending): string[] {
+	const out: string[] = [];
+	const news = p.untracked.filter(Boolean);
+	const mods = modifiedPaths(p);
+	const dels = p.deleted.filter(Boolean);
+	out.push(`Shared memories [review mode]: ${describe(news.length + mods.length + dels.length, p.unpushed)}`);
+
+	for (const f of news) {
+		out.push(`+ NEW  <file://${urlEncodePath(join(repo, f))}>`);
+		const pv = preview(repo, f);
+		if (pv !== "") out.push(`       "${pv}"`);
+	}
+
+	for (const { added, deleted, path } of p.numstats) {
+		if (path === "") continue;
+		out.push(`~ MOD  <file://${urlEncodePath(join(repo, path))}>  (+${added} -${deleted})`);
+		out.push(`       Diff: git -C .claude/.memories-repo diff -- ${path}`);
+	}
+
+	// Per-file `git log` is one process each; the cap keeps a large audit predictable.
+	let idx = 0;
+	for (const f of dels) {
+		idx++;
+		if (idx <= 20) {
+			const last = gitOut(repo, ["log", "-1", "--format=%cr", "HEAD", "--", f]) || "?";
+			out.push(`- DEL  ${f}  (last modified ${last})`);
+		} else {
+			out.push(`- DEL  ${f}`);
+		}
+		out.push(`       Recover: git -C .claude/.memories-repo checkout HEAD -- ${f}`);
+	}
+
+	out.push("");
+	if (p.unpushed > 0) {
+		out.push(`  Note: ${p.unpushed} local commit(s) not yet on the remote.`);
+		out.push(
+			"        Push: git -C .claude/.memories-repo pull --rebase --autostash && git -C .claude/.memories-repo push",
+		);
+		out.push("");
+	}
+	out.push("Approve all:           /approve-memories  [optional commit reason]");
+	out.push("Discard local changes: git -C .claude/.memories-repo checkout -- memories/ \\");
+	out.push("                       && git -C .claude/.memories-repo clean -f -- memories/");
+	return out;
+}
diff --git a/runtime/pull.mts b/runtime/pull.mts
new file mode 100755
index 0000000..4bf23d5
--- /dev/null
+++ b/runtime/pull.mts
@@ -0,0 +1,58 @@
+#!/usr/bin/env -S node --experimental-strip-types --disable-warning=ExperimentalWarning
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { additionalContext, failOpen, isJsonStream, readStdin, warn } from "./lib/hook-io.mts";
+import { gitLines, gitPresent, isWorkTree, unpushedCount, git } from "./lib/git.mts";
+import { MODES, resolveMode } from "./lib/mode.mts";
+import { memoriesRepo, projectRoot } from "./lib/paths.mts";
+
+const NAME = "memories_pull";
+
+failOpen(NAME, () => {
+	if (!gitPresent()) return warn(`${NAME}: git not found; skipping`);
+	if (!isJsonStream(readStdin())) return warn(`${NAME}: stdin is not valid JSON; skipping`);
+
+	const project = projectRoot(import.meta.dirname);
+	const repo = memoriesRepo(project);
+	if (!isWorkTree(repo)) {
+		return warn(`${NAME}: ${repo} is not a git worktree; skipping (project_root=${project})`);
+	}
+
+	const raw = process.env["MEMORIES_AUTOPUSH_MODE"];
+	const { mode, unrecognised } = resolveMode(raw);
+	const modeWarning =
+		unrecognised === null
+			? ""
+			: `Shared memories: unknown MEMORIES_AUTOPUSH_MODE='${unrecognised}' — falling back to auto. Fix the value in .claude/settings.local.json (valid: ${MODES.join(", ")}) and restart the session.`;
+
+	git(repo, ["pull", "--ff-only", "--quiet"]);
+
+	if (mode === "review") {
+		try {
+			rmSync(join(repo, ".review-shown"), { force: true });
+		} catch {
+			/* the bash ignores this too */
+		}
+	}
+
+	const uncommitted = gitLines(repo, ["status", "--porcelain", "--", "memories/"]).length;
+	const unpushed = unpushedCount(repo);
+
+	let pending = "";
+	if (uncommitted > 0 || unpushed > 0) {
+		const joined =
+			uncommitted > 0 && unpushed > 0
+				? `${uncommitted} uncommitted file(s), ${unpushed} unpushed commit(s)`
+				: uncommitted > 0
+					? `${uncommitted} uncommitted file(s)`
+					: `${unpushed} unpushed commit(s)`;
+		pending =
+			mode === "review"
+				? `Shared memories: ${joined} awaiting review (MEMORIES_AUTOPUSH_MODE=review). End a turn to see the per-file report with approve/discard commands.`
+				: `Shared memories have lingering state: ${joined}. The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.`;
+	}
+
+	const msg = modeWarning && pending ? `${modeWarning}\n\n${pending}` : modeWarning || pending;
+	if (msg === "") return;
+	additionalContext("SessionStart", msg);
+});
diff --git a/scripts/configure-memories.sh b/scripts/configure-memories.sh
deleted file mode 100755
index 15bc9f3..0000000
--- a/scripts/configure-memories.sh
+++ /dev/null
@@ -1,301 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-# Runs during `mcs sync` after components install. Idempotent and self-healing:
-# handles first-time setup, missing symlinks, broken symlinks pointing at a
-# still-live checkout, AND migration from an existing non-symlink memories
-# directory (e.g. memories an engineer already captured via mcs-cli/memory or
-# Claude Code's native memory feature before adopting this pack).
-#
-# Layout on disk:
-#   .claude/.memories-repo/            ← hidden sparse clone of the memories branch
-#     memories/
-#       learning_*.md / decision_*.md
-#   .claude/memories                   ← symlink → .memories-repo/memories
-#
-# The checkout uses single-branch partial-blobless sparse-checkout so only the
-# memory markdowns materialize on disk — pack plumbing stays in git history but
-# never hits the working tree.
-#
-# Migrated files are checked against the branch's deletion history: anything a
-# past memory-audit removed is held back rather than re-imported, so a stale
-# local KB can't silently republish memories the team already curated away.
-
-memories_link="$MCS_PROJECT_PATH/.claude/memories"
-repo_dir="$MCS_PROJECT_PATH/.claude/.memories-repo"
-repo_url="${MCS_RESOLVED_MEMORIES_REPO_URL:-}"
-branch="${MCS_RESOLVED_MEMORIES_BRANCH:-main}"
-migration_backup=""
-# Initialized before the ERR trap installs — trap body reads it under `set -u`.
-created_repo_dir=0
-
-if [ -z "$repo_url" ]; then
-  echo "MEMORIES_REPO_URL not resolved; skipping memories clone." >&2
-  exit 0
-fi
-
-if ! command -v git >/dev/null 2>&1; then
-  echo "git is required for mcs-shared-memories setup but was not found on PATH." >&2
-  exit 1
-fi
-
-link_memories() {
-  ln -sfn .memories-repo/memories "$memories_link"
-  # Fail fast if the target doesn't resolve. Without this check, a dangling
-  # symlink would survive long enough for the migration import loop below to
-  # `mv` files into a non-existent directory, then the ERR trap fires too late
-  # to give a clear diagnostic.
-  if [ ! -d "$memories_link/" ]; then
-    echo "ERROR: $memories_link → .memories-repo/memories points to a missing directory." >&2
-    echo "  The sparse checkout at $repo_dir did not materialize memories/." >&2
-    return 1
-  fi
-}
-
-# If setup fails AFTER we've moved the user's existing memories aside, put them
-# back so we never leave an engineer with no memory files at all. Also sweeps
-# up a half-written $repo_dir so a failed clone can't jam Case 4 on the retry.
-restore_backup_on_error() {
-  if [ "$created_repo_dir" = "1" ] && [ -d "$repo_dir" ] && [ ! -d "$repo_dir/.git" ]; then
-    rm -rf "$repo_dir"
-  fi
-
-  # A dangling symlink (link exists, target doesn't) must count as "not present"
-  # here — otherwise the original `[ ! -L ]` guard skipped restore and stranded
-  # the engineer's memories in the migration backup. Sweep the broken link first
-  # so `mv backup memories` doesn't fail with "Not a directory".
-  if [ -L "$memories_link" ] && [ ! -e "$memories_link" ]; then
-    rm -f "$memories_link"
-  fi
-
-  if [ -n "$migration_backup" ] && [ -d "$migration_backup" ] && [ ! -e "$memories_link" ]; then
-    echo "Setup failed — restoring your original memories from $migration_backup to $memories_link" >&2
-    if ! mv "$migration_backup" "$memories_link"; then
-      echo "ERROR: Automatic restore failed. Your memories are preserved at:" >&2
-      echo "  $migration_backup" >&2
-      echo "Move this directory back to $memories_link manually." >&2
-    fi
-  fi
-}
-trap restore_backup_on_error ERR
-
-# ─── Case 1: healthy — symlink present and checkout live. Nothing to do. ───
-if [ -L "$memories_link" ] && \
-   git -C "$memories_link" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  echo "Shared memories already linked — leaving as-is."
-  exit 0
-fi
-
-# ─── Preflight: probe the remote BEFORE any filesystem mutation. ───────────
-# Catches no-SSH-key, no-network, revoked access, wrong URL, and missing
-# branch. Mirrors doctor-memories-remote.sh so both surfaces give the same
-# diagnostic. Healthy re-runs (Case 1 above) skip this and stay offline-safe.
-if ! err=$(git ls-remote --exit-code --heads "$repo_url" "$branch" 2>&1 >/dev/null); then
-  echo "Cannot set up shared memories — remote is unreachable or branch missing." >&2
-  echo "  remote: $repo_url" >&2
-  echo "  branch: $branch" >&2
-  echo "  error:  $err" >&2
-  echo "" >&2
-  echo "Common causes:" >&2
-  echo "  - SSH key not loaded — try: ssh-add ~/.ssh/<your-key>" >&2
-  echo "  - Network offline or VPN disconnected" >&2
-  echo "  - Access revoked on the shared repo" >&2
-  echo "  - Branch '$branch' does not exist on the remote" >&2
-  echo "" >&2
-  echo "Your existing memories at $memories_link have not been touched." >&2
-  exit 1
-fi
-
-# ─── Case 2: pre-existing non-symlink at the memories path ─────────────────
-# Could be empty (left over from an uninstalled pack) or populated (engineer
-# was already using mcs-cli/memory or Claude Code's automemory locally).
-# Migrate either way: back the directory up, then fall through to first-time
-# setup and import the contents afterward.
-if [ -e "$memories_link" ] && [ ! -L "$memories_link" ]; then
-  if [ ! -d "$memories_link" ]; then
-    echo "$memories_link exists but is not a directory or symlink; refusing to touch it." >&2
-    exit 0
-  fi
-
-  if [ -z "$(ls -A "$memories_link" 2>/dev/null)" ]; then
-    echo "Found empty $memories_link — removing and proceeding with fresh setup."
-    rmdir "$memories_link"
-  else
-    ts=$(date +%Y%m%d-%H%M%S)
-    migration_backup="$MCS_PROJECT_PATH/.claude/.memories-migration-$ts"
-    count=$(ls -1A "$memories_link" 2>/dev/null | wc -l | tr -d ' ')
-    echo "Found pre-existing $memories_link with $count entr(y/ies) — staging for migration..."
-    echo "  → backing up to $migration_backup"
-    mv "$memories_link" "$migration_backup"
-  fi
-fi
-
-# ─── Case 3: checkout is live but symlink is missing or broken — relink. ───
-if [ -d "$repo_dir/.git" ] && \
-   git -C "$repo_dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  echo "Memories checkout present, (re)linking $memories_link → .memories-repo/memories..."
-  rm -f "$memories_link"
-  link_memories
-else
-  # ─── Case 4: checkout dir exists but incomplete (no .git) — refuse. ──────
-  if [ -e "$repo_dir" ]; then
-    echo "$repo_dir exists but is not a valid git checkout; refusing to touch it." >&2
-    echo "Delete it manually and re-run \`mcs sync\` to re-clone." >&2
-    exit 0
-  fi
-
-  # ─── Case 5: nothing exists — first-time setup. ──────────────────────────
-  echo "Cloning shared memories (branch '$branch', sparse) into $repo_dir..."
-  created_repo_dir=1
-  git clone \
-    --sparse \
-    --filter=blob:none \
-    --branch "$branch" \
-    --single-branch \
-    "$repo_url" "$repo_dir"
-  git -C "$repo_dir" sparse-checkout set memories
-  # Bootstrap case: the remote branch may be empty (no memories/ tree yet) on
-  # first-ever pack adoption. Sparse-checkout exits 0 but materializes nothing,
-  # so the symlink we're about to create would dangle and the migration import
-  # below would fail with "No such file or directory". mkdir -p is a no-op once
-  # the directory is tracked.
-  mkdir -p "$repo_dir/memories"
-  link_memories
-fi
-
-# ─── Post-setup: import migration backup (shared wins on conflict). ────────
-# For every regular file in the backup, move it into the now-symlinked memories
-# folder unless a file of the same name already exists (in which case the
-# shared/team copy wins and the local one is preserved in the backup dir for
-# manual review). This protects against silent overwrite of team knowledge.
-if [ -n "$migration_backup" ] && [ -d "$migration_backup" ]; then
-  imported=0
-  skipped=0
-  resurrected=0
-  resurrected_files=""
-
-  # Paths this branch's history records as deleted (the header note explains why
-  # we care). Blobless clones keep every commit and tree, so this is offline and
-  # fast — ~0.1s over 600 commits. Deliberately un-piped: under `set -o pipefail`
-  # the ERR trap is inherited into command substitutions, and this block still
-  # runs with restore_backup_on_error armed. Duplicates are harmless for the
-  # membership test below, so `sort -u` buys nothing worth that risk, and
-  # `|| true` covers a bootstrap branch with no commits yet.
-  deleted_history=$(git -C "$repo_dir" log --all --diff-filter=D --name-only \
-    --format='' -- memories/ 2>/dev/null || true)
-  # Wrapping in newline sentinels turns the per-file lookup below into a pure
-  # builtin glob match: no `grep` fork per migrating file (a 133-file migration
-  # would otherwise spawn one each), and no second pipeline in this block.
-  nl=$'\n'
-  deleted_history_padded="$nl$deleted_history$nl"
-
-  shopt -s nullglob dotglob
-  for f in "$migration_backup"/*; do
-    [ -f "$f" ] || continue
-    name=$(basename "$f")
-    target="$memories_link/$name"
-    if [ -e "$target" ]; then
-      skipped=$((skipped + 1))
-    elif [[ "$deleted_history_padded" == *"$nl""memories/$name""$nl"* ]]; then
-      # Sentinels make this a whole-line match, equivalent to `grep -qxF`.
-      resurrected=$((resurrected + 1))
-      resurrected_files+="$name"$'\n'
-    else
-      mv "$f" "$target"
-      imported=$((imported + 1))
-    fi
-  done
-  shopt -u nullglob dotglob
-
-  # If nothing left in backup (no conflicts, no held-back files, no subdirs),
-  # clean it up.
-  if [ -z "$(ls -A "$migration_backup" 2>/dev/null)" ]; then
-    rmdir "$migration_backup"
-    echo "Migration: imported $imported local memory file(s); $skipped conflict(s) (shared version kept)."
-  else
-    echo "Migration: imported $imported local memory file(s); $skipped conflict(s) (shared version kept); $resurrected previously-deleted file(s) held back."
-    echo "  Kept at $migration_backup for review."
-  fi
-fi
-
-# Clear the ERR trap now that we're past the risky section.
-trap - ERR
-
-# ─── Report files held back as previously-deleted. ─────────────────────────
-# Deliberately placed after `trap - ERR`: the per-file `git log` lookups below
-# would otherwise risk firing restore_backup_on_error mid-report.
-if [ "${resurrected:-0}" -gt 0 ]; then
-  echo ""
-  echo "Held back $resurrected file(s) previously deleted from the shared repo:"
-  res_idx=0
-  while IFS= read -r name; do
-    [ -n "$name" ] || continue
-    res_idx=$((res_idx + 1))
-    echo "  - $name"
-    # Cap the per-file lookups so a large migration stays fast.
-    # keep in sync with hooks/memories_autopush.sh deletion-report cap
-    if [ "$res_idx" -le 20 ]; then
-      why=$(git -C "$repo_dir" log -1 --format='%h %s' --diff-filter=D \
-        -- "memories/$name" 2>/dev/null || true)
-      # A plain `if`, not `[ -n … ] && echo` — the latter returns 1 when $why is
-      # empty and, as the last command in this block, would trip `set -e`.
-      if [ -n "$why" ]; then
-        echo "      deleted by $why"
-      fi
-    fi
-  done <<< "$resurrected_files"
-  echo ""
-  echo "Someone removed these deliberately, so they were not re-imported or pushed."
-  echo "To re-add one anyway: cp '$migration_backup/<file>' '$memories_link/<file>'"
-fi
-
-# ─── Auto-commit migrated memories if any well-named ones landed. ──────────
-# Without this step the migrated files are untracked in the sparse checkout,
-# which (a) makes SessionStart emit a scary "lingering state" warning on the
-# next session and (b) delays team sharing until the next Stop hook fires.
-# Committing and pushing right here closes both gaps.
-#
-# Guardrail applied here mirrors the Stop hook's pattern: only files matching
-# ^memories/(learning|decision)_*.md get staged. Non-conforming files (e.g.
-# a personal scratch.txt) stay untracked with a rename nudge — the Stop hook's
-# all-or-nothing guardrail will catch them again if the engineer ignores the
-# nudge, so the pressure to rename is consistent.
-if [ "${imported:-0}" -gt 0 ]; then
-  # keep in sync with hooks/memories_autopush.sh allowed_pattern,
-  # hooks/memories_announce.sh regex, and commands/approve-memories.md guardrail
-  allowed_pattern='^memories/(learning|decision)_[a-zA-Z0-9_-]+\.md$'
-
-  untracked=$(git -C "$repo_dir" ls-files --others --exclude-standard --full-name -- memories/ 2>/dev/null | grep -v '^$' || true)
-  good_files=$(echo "$untracked" | grep -E  "$allowed_pattern" || true)
-  bad_files=$( echo "$untracked" | grep -Ev "$allowed_pattern" || true)
-
-  if [ -n "$good_files" ]; then
-    while IFS= read -r f; do
-      [ -n "$f" ] && git -C "$repo_dir" add -- "$f"
-    done <<< "$good_files"
-
-    host=$(hostname -s)
-    git -C "$repo_dir" commit -m "auto: migrate local memories from $host" --quiet
-
-    # Rebase in case teammates pushed while we were cloning / migrating, then push.
-    if git -C "$repo_dir" pull --rebase --autostash --quiet 2>/dev/null; then
-      if git -C "$repo_dir" push --quiet 2>/dev/null; then
-        echo "Pushed migrated memories to the shared branch."
-      else
-        echo "Migrated memories committed locally; push failed (auth or network?). The next Stop hook will retry."
-      fi
-    else
-      git -C "$repo_dir" rebase --abort 2>/dev/null || true
-      echo "Migrated memories committed locally; rebase conflict blocked the push. The next Stop hook will retry."
-    fi
-  fi
-
-  if [ -n "$bad_files" ]; then
-    echo "Note: these migrated files don't match the naming convention and were left untracked:"
-    echo "$bad_files" | sed 's/^/  - /'
-    echo "Rename them to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so they can be shared with the team."
-  fi
-fi
-
-count=$(ls "$memories_link"/*.md 2>/dev/null | wc -l | tr -d ' ')
-echo "Done. $count memory file(s) available at $memories_link."
diff --git a/scripts/configure-memories.ts b/scripts/configure-memories.ts
new file mode 100755
index 0000000..c382de2
--- /dev/null
+++ b/scripts/configure-memories.ts
@@ -0,0 +1,285 @@
+#!/usr/bin/env -S node --experimental-strip-types --disable-warning=ExperimentalWarning
+import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { git, gitLines, gitOut, gitPresent, isWorkTree } from "../runtime/lib/git.mts";
+import { ALLOWED_PATTERN } from "../runtime/lib/naming.mts";
+
+const out = (line: string) => process.stdout.write(`${line}\n`);
+const err = (line: string) => process.stderr.write(`${line}\n`);
+
+const project = process.env["MCS_PROJECT_PATH"] ?? "";
+const link = `${project}/.claude/memories`;
+const repoDir = `${project}/.claude/.memories-repo`;
+const repoUrl = process.env["MCS_RESOLVED_MEMORIES_REPO_URL"] ?? "";
+const branch = process.env["MCS_RESOLVED_MEMORIES_BRANCH"] || "main";
+
+let migrationBackup = "";
+let createdRepoDir = false;
+
+const isSymlink = (p: string): boolean => {
+	try {
+		return lstatSync(p).isSymbolicLink();
+	} catch {
+		return false;
+	}
+};
+const exists = (p: string): boolean => {
+	try {
+		lstatSync(p);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const isDir = (p: string): boolean => {
+	try {
+		return statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+};
+const entries = (p: string): string[] => {
+	try {
+		return readdirSync(p).sort();
+	} catch {
+		return [];
+	}
+};
+
+function linkMemories(): void {
+	if (exists(link)) unlinkSync(link);
+	symlinkSync(".memories-repo/memories", link);
+	// A dangling link would survive long enough for the import below to move files into nothing.
+	if (!isDir(link)) {
+		err(`ERROR: ${link} → .memories-repo/memories points to a missing directory.`);
+		err(`  The sparse checkout at ${repoDir} did not materialize memories/.`);
+		throw new Error("link target missing");
+	}
+}
+
+/** Never leave an engineer with no memories: put the backup back if setup failed after moving it. */
+function restoreBackup(): void {
+	if (createdRepoDir && isDir(repoDir) && !existsSync(join(repoDir, ".git"))) {
+		rmSync(repoDir, { recursive: true, force: true });
+	}
+	// A dangling symlink counts as "not present" here, and must be swept before the move.
+	if (isSymlink(link) && !existsSync(link)) unlinkSync(link);
+	if (migrationBackup !== "" && isDir(migrationBackup) && !exists(link)) {
+		err(`Setup failed — restoring your original memories from ${migrationBackup} to ${link}`);
+		try {
+			renameSync(migrationBackup, link);
+		} catch {
+			err("ERROR: Automatic restore failed. Your memories are preserved at:");
+			err(`  ${migrationBackup}`);
+			err(`Move this directory back to ${link} manually.`);
+		}
+	}
+}
+
+function stamp(): string {
+	const d = new Date();
+	const p = (n: number) => String(n).padStart(2, "0");
+	return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+function main(): void {
+	if (repoUrl === "") {
+		err("MEMORIES_REPO_URL not resolved; skipping memories clone.");
+		process.exit(0);
+	}
+	if (project === "") {
+		err("MCS_PROJECT_PATH is not set; cannot locate the project's .claude directory.");
+		process.exit(1);
+	}
+	if (!gitPresent()) {
+		err("git is required for mcs-shared-memories setup but was not found on PATH.");
+		process.exit(1);
+	}
+
+	// Case 1: healthy.
+	if (isSymlink(link) && isWorkTree(link)) {
+		out("Shared memories already linked — leaving as-is.");
+		process.exit(0);
+	}
+
+	// Preflight before any filesystem mutation, so a bad remote leaves memories untouched.
+	const probe = git(process.cwd(), ["ls-remote", "--exit-code", "--heads", repoUrl, branch]);
+	if (!probe.ok) {
+		err("Cannot set up shared memories — remote is unreachable or branch missing.");
+		err(`  remote: ${repoUrl}`);
+		err(`  branch: ${branch}`);
+		err(`  error:  ${probe.stderr.replace(/\n$/, "") || (probe.failure ?? "")}`);
+		err("");
+		err("Common causes:");
+		err("  - SSH key not loaded — try: ssh-add ~/.ssh/<your-key>");
+		err("  - Network offline or VPN disconnected");
+		err("  - Access revoked on the shared repo");
+		err(`  - Branch '${branch}' does not exist on the remote`);
+		err("");
+		err(`Your existing memories at ${link} have not been touched.`);
+		process.exit(1);
+	}
+
+	// Case 2: a real directory where the symlink belongs.
+	if (exists(link) && !isSymlink(link)) {
+		if (!isDir(link)) {
+			err(`${link} exists but is not a directory or symlink; refusing to touch it.`);
+			process.exit(0);
+		}
+		const contents = entries(link);
+		if (contents.length === 0) {
+			out(`Found empty ${link} — removing and proceeding with fresh setup.`);
+			rmdirSync(link);
+		} else {
+			migrationBackup = `${project}/.claude/.memories-migration-${stamp()}`;
+			out(`Found pre-existing ${link} with ${contents.length} entr(y/ies) — staging for migration...`);
+			out(`  → backing up to ${migrationBackup}`);
+			renameSync(link, migrationBackup);
+		}
+	}
+
+	if (existsSync(join(repoDir, ".git")) && isWorkTree(repoDir)) {
+		// Case 3: checkout is live, the link is missing or broken.
+		out(`Memories checkout present, (re)linking ${link} → .memories-repo/memories...`);
+		if (exists(link)) unlinkSync(link);
+		linkMemories();
+	} else if (exists(repoDir)) {
+		// Case 4: something is there but it is not a checkout.
+		err(`${repoDir} exists but is not a valid git checkout; refusing to touch it.`);
+		err("Delete it manually and re-run `mcs sync` to re-clone.");
+		process.exit(0);
+	} else {
+		// Case 5: first-time setup.
+		out(`Cloning shared memories (branch '${branch}', sparse) into ${repoDir}...`);
+		createdRepoDir = true;
+		const clone = git(
+			process.cwd(),
+			["clone", "--sparse", "--filter=blob:none", "--branch", branch, "--single-branch", repoUrl, repoDir],
+			{ inheritStderr: true },
+		);
+		// The bash has no handler here: `set -e` fires the ERR trap, which restores
+		// the backup, and the script exits with git's own status.
+		if (!clone.ok) {
+			restoreBackup();
+			process.exit(clone.exit ?? 1);
+		}
+		// Materialises memories/; the mkdir below would otherwise mask its failure.
+		const sparse = git(repoDir, ["sparse-checkout", "set", "memories"], { inheritStderr: true });
+		if (!sparse.ok) {
+			restoreBackup();
+			process.exit(sparse.exit ?? 1);
+		}
+		// A bootstrap branch has no memories/ tree, and the link would dangle.
+		mkdirSync(join(repoDir, "memories"), { recursive: true });
+		linkMemories();
+	}
+
+	let imported = 0;
+	let skipped = 0;
+	const resurrected: string[] = [];
+
+	if (migrationBackup !== "" && isDir(migrationBackup)) {
+		// Blobless clones keep every commit and tree, so this is offline and fast.
+		const deletedHistory = new Set(
+			gitLines(repoDir, ["log", "--all", "--diff-filter=D", "--name-only", "--format=", "--", "memories/"]),
+		);
+
+		for (const name of entries(migrationBackup)) {
+			const from = join(migrationBackup, name);
+			// `[ -f "$f" ] || continue` is false for a dangling symlink rather than fatal.
+			let entry: ReturnType<typeof statSync>;
+			try {
+				entry = statSync(from);
+			} catch {
+				continue;
+			}
+			if (!entry.isFile()) continue;
+			const target = join(link, name);
+			if (exists(target)) {
+				skipped++;
+			} else if (deletedHistory.has(`memories/${name}`)) {
+				resurrected.push(name);
+			} else {
+				renameSync(from, target);
+				imported++;
+			}
+		}
+
+		if (entries(migrationBackup).length === 0) {
+			rmdirSync(migrationBackup);
+			out(`Migration: imported ${imported} local memory file(s); ${skipped} conflict(s) (shared version kept).`);
+		} else {
+			out(
+				`Migration: imported ${imported} local memory file(s); ${skipped} conflict(s) (shared version kept); ${resurrected.length} previously-deleted file(s) held back.`,
+			);
+			out(`  Kept at ${migrationBackup} for review.`);
+		}
+	}
+
+	if (resurrected.length > 0) {
+		out("");
+		out(`Held back ${resurrected.length} file(s) previously deleted from the shared repo:`);
+		let idx = 0;
+		for (const name of resurrected) {
+			idx++;
+			out(`  - ${name}`);
+			if (idx <= 20) {
+				const why = gitOut(repoDir, ["log", "-1", "--format=%h %s", "--diff-filter=D", "--", `memories/${name}`]);
+				if (why !== "") out(`      deleted by ${why}`);
+			}
+		}
+		out("");
+		out("Someone removed these deliberately, so they were not re-imported or pushed.");
+		out(`To re-add one anyway: cp '${migrationBackup}/<file>' '${link}/<file>'`);
+	}
+
+	if (imported > 0) {
+		const untracked = gitLines(repoDir, ["ls-files", "--others", "--exclude-standard", "--full-name", "--", "memories/"]);
+		const good = untracked.filter((f) => ALLOWED_PATTERN.test(f));
+		const bad = untracked.filter((f) => !ALLOWED_PATTERN.test(f));
+
+		if (good.length > 0) {
+			for (const f of good) {
+				const add = git(repoDir, ["add", "--", f], { inheritStderr: true });
+				if (!add.ok) process.exit(add.exit ?? 1);
+			}
+			// Unchecked, the push below succeeds vacuously and reports one that never happened.
+			const commit = git(repoDir, ["commit", "-m", `auto: migrate local memories from ${hostname().split(".")[0]}`, "--quiet"], {
+				inheritStderr: true,
+			});
+			if (!commit.ok) process.exit(commit.exit ?? 1);
+			if (git(repoDir, ["pull", "--rebase", "--autostash", "--quiet"]).ok) {
+				if (git(repoDir, ["push", "--quiet"]).ok) {
+					out("Pushed migrated memories to the shared branch.");
+				} else {
+					out("Migrated memories committed locally; push failed (auth or network?). The next Stop hook will retry.");
+				}
+			} else {
+				git(repoDir, ["rebase", "--abort"]);
+				out("Migrated memories committed locally; rebase conflict blocked the push. The next Stop hook will retry.");
+			}
+		}
+
+		if (bad.length > 0) {
+			out("Note: these migrated files don't match the naming convention and were left untracked:");
+			for (const f of bad) out(`  - ${f}`);
+			out(
+				"Rename them to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so they can be shared with the team.",
+			);
+		}
+	}
+
+	// Dotfiles are excluded because the bash counted with an `ls *.md` glob.
+	const mds = entries(link).filter((f) => !f.startsWith(".") && f.endsWith(".md"));
+	out(`Done. ${mds.length} memory file(s) available at ${link}.`);
+}
+
+try {
+	main();
+} catch (e) {
+	restoreBackup();
+	const detail = e instanceof Error ? e.message : String(e);
+	if (detail !== "link target missing") err(`configure-memories: ${detail}`);
+	process.exit(1);
+}
diff --git a/scripts/doctor-memories-remote.sh b/scripts/doctor-memories-remote.sh
deleted file mode 100755
index 48dd280..0000000
--- a/scripts/doctor-memories-remote.sh
+++ /dev/null
@@ -1,45 +0,0 @@
-#!/bin/bash
-# Remote-access health check for `mcs doctor`.
-#
-# Exit codes per the MCS shellScript doctor contract:
-#   0 = pass (remote reachable, auth working)
-#   1 = fail
-#   2 = warning (checkout exists but remote unreachable — pushes will queue)
-#   3 = skip (no checkout yet; doctor-memories.sh handles setup issues)
-#
-# Uses `git ls-remote origin` as a protocol-agnostic auth + reachability probe:
-# it works for SSH, HTTPS, and git:// remotes, doesn't need a working tree,
-# and returns fast. Failure modes it catches:
-#   - SSH key not loaded or expired (ssh-add needed)
-#   - Network offline or firewall blocking the host
-#   - Remote URL changed or repo moved/deleted
-#   - Credentials revoked / access removed
-
-set -u
-
-project="${MCS_PROJECT_PATH:-$PWD}"
-repo_dir="$project/.claude/.memories-repo"
-
-# No checkout → skip. The setup-health check flags this separately.
-if [ ! -d "$repo_dir/.git" ]; then
-  exit 3
-fi
-
-# Probe the remote. Suppress stdout (ref list could be large), capture stderr
-# for diagnostics on failure.
-if err=$(git -C "$repo_dir" ls-remote --quiet origin 2>&1 >/dev/null); then
-  exit 0
-fi
-
-remote_url=$(git -C "$repo_dir" remote get-url origin 2>/dev/null || echo "<unknown>")
-echo "Cannot reach the shared memories remote:"
-echo "  remote: $remote_url"
-echo "  error:  $err"
-echo ""
-echo "Common causes:"
-echo "  - SSH key not loaded — try: ssh-add ~/.ssh/<your-key>"
-echo "  - Network offline or VPN disconnected"
-echo "  - Access revoked on the shared repo"
-echo ""
-echo "Memories still work locally; auto-push will retry on each Claude Stop once the remote is reachable."
-exit 2
diff --git a/scripts/doctor-memories-remote.ts b/scripts/doctor-memories-remote.ts
new file mode 100755
index 0000000..52d7d9f
--- /dev/null
+++ b/scripts/doctor-memories-remote.ts
@@ -0,0 +1,30 @@
+#!/usr/bin/env -S node --experimental-strip-types --disable-warning=ExperimentalWarning
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { git, gitOut } from "../runtime/lib/git.mts";
+
+// mcs shellScript doctor contract: 0 pass, 1 fail, 2 warn, 3 skip.
+const project = process.env["MCS_PROJECT_PATH"] || process.cwd();
+const repo = join(project, ".claude", ".memories-repo");
+
+// No checkout is the setup check's problem, not this one's.
+if (!existsSync(join(repo, ".git"))) process.exit(3);
+
+const probe = git(repo, ["ls-remote", "--quiet", "origin"]);
+if (probe.ok) process.exit(0);
+
+const url = gitOut(repo, ["remote", "get-url", "origin"]) || "<unknown>";
+const lines = [
+	"Cannot reach the shared memories remote:",
+	`  remote: ${url}`,
+	`  error:  ${probe.stderr.replace(/\n$/, "") || (probe.failure ?? "")}`,
+	"",
+	"Common causes:",
+	"  - SSH key not loaded — try: ssh-add ~/.ssh/<your-key>",
+	"  - Network offline or VPN disconnected",
+	"  - Access revoked on the shared repo",
+	"",
+	"Memories still work locally; auto-push will retry on each Claude Stop once the remote is reachable.",
+];
+process.stdout.write(`${lines.join("\n")}\n`);
+process.exit(2);
diff --git a/scripts/doctor-memories.sh b/scripts/doctor-memories.sh
deleted file mode 100755
index 9d72f70..0000000
--- a/scripts/doctor-memories.sh
+++ /dev/null
@@ -1,40 +0,0 @@
-#!/bin/bash
-# Shared memories health check for `mcs doctor`.
-#
-# Exit codes per the MCS shellScript doctor contract:
-#   0 = pass
-#   1 = fail
-#   2 = warning
-#   3 = skip
-#
-# Verifies both halves of the on-disk setup:
-#   1. .claude/.memories-repo/ is a real git checkout
-#   2. The configured symlink under .claude/ resolves to that checkout
-
-set -u
-
-project="${MCS_PROJECT_PATH:-$PWD}"
-memories_link="$project/.claude/memories"
-repo_dir="$project/.claude/.memories-repo"
-
-problems=()
-
-if [ ! -d "$repo_dir/.git" ]; then
-  problems+=("git checkout missing at $repo_dir (run 'mcs sync' to re-clone)")
-fi
-
-if [ ! -L "$memories_link" ]; then
-  problems+=("symlink missing at $memories_link (run 'mcs sync' to relink)")
-elif ! git -C "$memories_link" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  problems+=("symlink exists but doesn't resolve to a git checkout (run 'mcs sync' to repair)")
-fi
-
-if [ ${#problems[@]} -gt 0 ]; then
-  echo "Shared memories setup is unhealthy:"
-  for p in "${problems[@]}"; do
-    echo "  - $p"
-  done
-  exit 1
-fi
-
-exit 0
diff --git a/scripts/doctor-memories.ts b/scripts/doctor-memories.ts
new file mode 100755
index 0000000..97c2661
--- /dev/null
+++ b/scripts/doctor-memories.ts
@@ -0,0 +1,34 @@
+#!/usr/bin/env -S node --experimental-strip-types --disable-warning=ExperimentalWarning
+import { existsSync, lstatSync } from "node:fs";
+import { join } from "node:path";
+import { isWorkTree } from "../runtime/lib/git.mts";
+
+// mcs shellScript doctor contract: 0 pass, 1 fail, 2 warn, 3 skip.
+const project = process.env["MCS_PROJECT_PATH"] || process.cwd();
+const link = join(project, ".claude", "memories");
+const repo = join(project, ".claude", ".memories-repo");
+
+const isSymlink = (p: string): boolean => {
+	try {
+		return lstatSync(p).isSymbolicLink();
+	} catch {
+		return false;
+	}
+};
+
+const problems: string[] = [];
+if (!existsSync(join(repo, ".git"))) {
+	problems.push(`git checkout missing at ${repo} (run 'mcs sync' to re-clone)`);
+}
+if (!isSymlink(link)) {
+	problems.push(`symlink missing at ${link} (run 'mcs sync' to relink)`);
+} else if (!isWorkTree(link)) {
+	problems.push("symlink exists but doesn't resolve to a git checkout (run 'mcs sync' to repair)");
+}
+
+if (problems.length > 0) {
+	process.stdout.write("Shared memories setup is unhealthy:\n");
+	for (const p of problems) process.stdout.write(`  - ${p}\n`);
+	process.exit(1);
+}
+process.exit(0);
diff --git a/techpack.yaml b/techpack.yaml
index d4c4a69..b8ae5d5 100644
--- a/techpack.yaml
+++ b/techpack.yaml
@@ -3,13 +3,18 @@ identifier: shared-memories
 displayName: "Shared Memories"
 description: Team-shared Claude Code memories via a dedicated git repo
 author: Bruno Guidolim
-minMCSVersion: "2026.4.12"
+minMCSVersion: "2026.9.3"
 
 # Doctor-check scripts are wired via `supplementaryDoctorChecks.command`, which
 # the unreferenced-file heuristic doesn't inspect. Silence those warnings.
+# The rest is maintainer-only: nothing under them is installed.
 ignore:
-  - scripts/doctor-memories.sh
-  - scripts/doctor-memories-remote.sh
+  - scripts/doctor-memories.ts
+  - scripts/doctor-memories-remote.ts
+  - tests/
+  - .github/
+  - package.json
+  - tsconfig.json
 
 prompts:
   - key: MEMORIES_REPO_URL
@@ -35,31 +40,50 @@ prompts:
 
 components:
   # ── Dependencies ──────────────────────────────────────────
-  - id: jq
-    description: JSON processor required by hook scripts
-    brew: jq
+  - id: node
+    displayName: Node.js
+    description: Runtime for the hooks and pack scripts. Node 22.6+ runs the TypeScript directly, with no build step.
+    brew: node
+
+  # ── Runtime ───────────────────────────────────────────────
+  # The hook entry points are installed by the hook components below; this ships
+  # the library they import, beside them, so `./lib/...` resolves the same way in
+  # the pack checkout and once installed.
+  - id: runtime
+    displayName: Shared memories runtime
+    description: The library the hooks import. Installed beside them, in .claude/hooks/shared-memories/lib/. `.mts` so module type never depends on the consumer's package.json.
+    isRequired: true
+    dependencies: [node]
+    type: configuration
+    installAction:
+      type: copyPackFile
+      source: runtime/lib
+      destination: hooks/shared-memories/lib
+      fileType: generic
 
   # ── Hooks ─────────────────────────────────────────────────
   - id: hook-memories-pull
     displayName: Pull shared memories and flag stuck state
     description: Fast-forwards the shared memories checkout on SessionStart. If a previous Stop hook's auto-push left uncommitted or unpushed work behind, emits a system-reminder warning so the engineer knows.
-    dependencies: [jq]
+    dependencies: [node, runtime]
     hookEvent: SessionStart
+    hookInterpreter: node --experimental-strip-types --disable-warning=ExperimentalWarning
     hookTimeout: 15
     hook:
-      source: hooks/memories_pull.sh
-      destination: memories_pull.sh
+      source: runtime/pull.mts
+      destination: pull.mts
 
   - id: hook-memories-autopush
     displayName: Sync shared memories
     description: After Claude stops, handles new/modified memory files according to MEMORIES_AUTOPUSH_MODE (auto/full/review). Default auto matches today — writes auto-pushed, deletions parked for manual review. Unconventional filenames halt everything until fixed in all modes. See README for the mode reference.
-    dependencies: [jq]
+    dependencies: [node, runtime]
     hookEvent: Stop
+    hookInterpreter: node --experimental-strip-types --disable-warning=ExperimentalWarning
     hookTimeout: 30
     hookAsync: true
     hook:
-      source: hooks/memories_autopush.sh
-      destination: memories_autopush.sh
+      source: runtime/autopush.mts
+      destination: autopush.mts
 
   # ── Commands ──────────────────────────────────────────────
   - id: command-approve-memories
@@ -72,13 +96,14 @@ components:
   - id: hook-memories-announce
     displayName: Surface review-mode memory writes to Claude
     description: PostToolUse hook that injects additionalContext after a memory file is written, only when MEMORIES_AUTOPUSH_MODE=review. Lets Claude proactively mention pending memory review in conversation. Silent in auto/full modes.
-    dependencies: [jq]
+    dependencies: [node, runtime]
     hookEvent: PostToolUse
+    hookInterpreter: node --experimental-strip-types --disable-warning=ExperimentalWarning
     hookMatcher: Write|Edit|MultiEdit
     hookTimeout: 5
     hook:
-      source: hooks/memories_announce.sh
-      destination: memories_announce.sh
+      source: runtime/announce.mts
+      destination: announce.mts
 
   # ── Configuration ─────────────────────────────────────────
   - id: settings
@@ -102,16 +127,16 @@ templates:
     contentFile: templates/instructions.md
 
 configureProject:
-  script: scripts/configure-memories.sh
+  script: scripts/configure-memories.ts
 
 supplementaryDoctorChecks:
   - type: shellScript
     name: Shared memories setup (checkout + symlink)
     section: Shared Memories
-    command: scripts/doctor-memories.sh
-    fixScript: scripts/configure-memories.sh
+    command: scripts/doctor-memories.ts
+    fixScript: scripts/configure-memories.ts
 
   - type: shellScript
     name: Shared memories remote access (auth + reachability)
     section: Shared Memories
-    command: scripts/doctor-memories-remote.sh
+    command: scripts/doctor-memories-remote.ts
diff --git a/tests/configure.test.ts b/tests/configure.test.ts
new file mode 100644
index 0000000..771c2db
--- /dev/null
+++ b/tests/configure.test.ts
@@ -0,0 +1,301 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { git, readGolden, runConfigure, type ConfigureFixture, type RunResult } from "./harness.ts";
+
+
+/**
+ * Behaviour is pinned to tests/golden/, recorded from the bash implementation
+ * this pack replaced and verified against it fixture by fixture before the bash
+ * was removed. A drift here is a change in what the pack does, not a stale test.
+ */
+function check(fx: ConfigureFixture, actual: RunResult): void {
+	const golden = readGolden(fx.name);
+	assert.ok(golden, `no golden recorded for "${fx.name}"`);
+
+	const wantStdout = fx.deviation?.stdout ? fx.deviation.stdout(golden.stdout) : golden.stdout;
+	const wantCode = fx.deviation?.code ?? golden.code;
+	if (fx.deviation) {
+		assert.ok(
+			wantStdout !== golden.stdout || wantCode !== golden.code,
+			`"${fx.name}" declares a deviation that is identical to the recorded bash behaviour`,
+		);
+	}
+
+	assert.equal(actual.stdout, wantStdout, `stdout drifted for "${fx.name}"`);
+	assert.equal(actual.code, wantCode, `exit code drifted for "${fx.name}"`);
+	assert.equal(actual.stderr, golden.stderr, `stderr drifted for "${fx.name}"`);
+	assert.equal(actual.git, golden.git, `resulting .claude/ drifted for "${fx.name}"`);
+	// A fixture where nothing happens passes vacuously, so pin what was recorded.
+	if (fx.expect) assert.match(golden.stdout + golden.stderr, fx.expect, `fixture "${fx.name}" never exercised what it claims to`);
+	if (fx.expectCode !== undefined) {
+		assert.equal(wantCode, fx.expectCode, `fixture "${fx.name}" did not reach the state it claims`);
+	}
+}
+
+function assertParity(fx: ConfigureFixture): void {
+	check(fx, runConfigure(fx));
+}
+
+const local = (claude: string, name: string, body = "Local memory.\n") => {
+	mkdirSync(join(claude, "memories"), { recursive: true });
+	writeFileSync(join(claude, "memories", name), body);
+};
+
+const fixtures: readonly ConfigureFixture[] = [
+	{
+		name: "case 5: fresh setup clones and links",
+		expectCode: 0,
+		expect: /Cloning shared memories \(branch 'main', sparse\)[\s\S]*Done\. 1 memory file\(s\) available/,
+	},
+	{
+		name: "case 1: an already-linked setup is left alone",
+		expectCode: 0,
+		expect: /Shared memories already linked — leaving as-is\./,
+		pre: (project, claude) => {
+			// A live checkout plus the symlink is the healthy state.
+			git(claude, "clone", "-q", join(project, "..", "remote.git"), join(claude, ".memories-repo"));
+			symlinkSync(".memories-repo/memories", join(claude, "memories"));
+		},
+	},
+	{
+		name: "case 2: an empty memories directory is removed",
+		expectCode: 0,
+		expect: /Found empty .*memories — removing and proceeding with fresh setup\./,
+		pre: (_project, claude) => mkdirSync(join(claude, "memories"), { recursive: true }),
+	},
+	{
+		name: "case 2: a populated memories directory migrates and pushes",
+		expectCode: 0,
+		expect: /staging for migration[\s\S]*Migration: imported 1 local memory file\(s\)[\s\S]*Pushed migrated memories/,
+		pre: (_project, claude) => local(claude, "learning_mine_own.md"),
+	},
+	{
+		name: "case 2: the shared copy wins a filename conflict",
+		expectCode: 0,
+		expect: /1 conflict\(s\) \(shared version kept\)/,
+		pre: (_project, claude) => local(claude, "learning_shared_seed.md", "My divergent copy.\n"),
+	},
+	{
+		name: "case 2: a previously deleted memory is held back",
+		expectCode: 0,
+		expect: /previously-deleted file\(s\) held back[\s\S]*deleted by <SHA> remove it/,
+		seed: (clone) => {
+			writeFileSync(join(clone, "memories", "learning_curated_away.md"), "Was here.\n");
+			git(clone, "add", "-A");
+			git(clone, "commit", "-qm", "add it");
+			rmSync(join(clone, "memories", "learning_curated_away.md"));
+			git(clone, "add", "-A");
+			git(clone, "commit", "-qm", "remove it");
+			git(clone, "push", "-q");
+		},
+		pre: (_project, claude) => local(claude, "learning_curated_away.md", "My stale copy.\n"),
+	},
+	{
+		name: "case 2: a badly named migrated file is left untracked",
+		expectCode: 0,
+		expect: /don't match the naming convention and were left untracked:\n  - memories\/scratch\.md/,
+		pre: (_project, claude) => {
+			local(claude, "learning_mine_own.md");
+			local(claude, "scratch.md", "Not conventional.\n");
+		},
+	},
+	{
+		// Distinguishes the final count's `*.md` filter from a bare entry count.
+		name: "case 2: a migrated non-markdown file is not counted as a memory",
+		expectCode: 0,
+		expect: /Done\. 2 memory file\(s\) available/,
+		pre: (_project, claude) => {
+			local(claude, "learning_mine_own.md");
+			local(claude, "notes.txt", "Not a memory.\n");
+		},
+	},
+	{
+		name: "case 3: a live checkout with no symlink is relinked",
+		expectCode: 0,
+		expect: /Memories checkout present, \(re\)linking/,
+		pre: (project, claude) => {
+			git(claude, "clone", "-q", join(project, "..", "remote.git"), join(claude, ".memories-repo"));
+		},
+	},
+	{
+		name: "case 4: a non-checkout at the repo path is refused",
+		expectCode: 0,
+		expect: /exists but is not a valid git checkout; refusing to touch it\./,
+		pre: (_project, claude) => mkdirSync(join(claude, ".memories-repo", "junk"), { recursive: true }),
+	},
+	{
+		name: "preflight: an unreachable remote touches nothing",
+		expectCode: 1,
+		expect: /Cannot set up shared memories — remote is unreachable or branch missing\./,
+		env: { MCS_RESOLVED_MEMORIES_REPO_URL: "/nonexistent/definitely-not-here.git" },
+		pre: (_project, claude) => local(claude, "learning_mine_own.md"),
+	},
+	{
+		name: "preflight: a missing branch touches nothing",
+		expectCode: 1,
+		expect: /Branch 'nope' does not exist on the remote/,
+		env: { MCS_RESOLVED_MEMORIES_BRANCH: "nope" },
+	},
+	{
+		name: "an unresolved repo url skips quietly",
+		expectCode: 0,
+		expect: /MEMORIES_REPO_URL not resolved; skipping memories clone\./,
+		env: { MCS_RESOLVED_MEMORIES_REPO_URL: "" },
+	},
+	{
+		name: "a regular file at the memories path is refused",
+		expectCode: 0,
+		expect: /exists but is not a directory or symlink; refusing to touch it\./,
+		pre: (_project, claude) => writeFileSync(join(claude, "memories"), "i am a file\n"),
+	},
+];
+
+describe("configure-memories — behaviour is pinned", () => {
+	for (const fx of fixtures) test(fx.name, () => assertParity(fx));
+});
+
+const audited: readonly ConfigureFixture[] = [
+	{
+		name: "audited: a bootstrap branch with no memories tree exits 2 without Done",
+		expectCode: 0,
+		expect: /Cloning shared memories/,
+		emptyRemote: true,
+		deviation: {
+			reason:
+				"The bash ended with `count=$(ls \"$link\"/*.md ...)`; under `set -e -o pipefail` an unmatched glob made ls exit 2 and killed the script, so a first install against an empty branch reported failure and printed no Done line.",
+			stdout: (recorded) => `${recorded}Done. 0 memory file(s) available at <TMP>/work/project/.claude/memories.\n`,
+			code: 0,
+		},
+	},
+	{
+		name: "audited: a subdirectory in the migration backup is left behind",
+		expectCode: 0,
+		expect: /Kept at .*\.memories-migration-<TS> for review\./,
+		pre: (_project, claude) => {
+			local(claude, "learning_mine_own.md");
+			mkdirSync(join(claude, "memories", "subdir"), { recursive: true });
+			writeFileSync(join(claude, "memories", "subdir", "x.md"), "x\n");
+		},
+	},
+	{
+		name: "audited: a dotted .md file migrates but is not counted",
+		expectCode: 0,
+		expect: /Done\. 2 memory file\(s\) available/,
+		pre: (_project, claude) => {
+			local(claude, "learning_mine_own.md");
+			writeFileSync(join(claude, "memories", ".hidden"), "h\n");
+			writeFileSync(join(claude, "memories", ".hidden.md"), "h\n");
+		},
+	},
+	{
+		name: "audited: a dangling symlink with no checkout is replaced",
+		expectCode: 0,
+		expect: /Cloning shared memories/,
+		pre: (_project, claude) => symlinkSync(".memories-repo/memories", join(claude, "memories")),
+	},
+	{
+		name: "audited: a symlink to a non-git directory beside a live checkout is relinked",
+		expectCode: 0,
+		expect: /Memories checkout present, \(re\)linking/,
+		pre: (project, claude) => {
+			git(claude, "clone", "-q", join(project, "..", "remote.git"), join(claude, ".memories-repo"));
+			mkdirSync(join(project, "elsewhere"), { recursive: true });
+			symlinkSync(join(project, "elsewhere"), join(claude, "memories"));
+		},
+	},
+	{
+		name: "audited: every migrated file conflicting imports nothing",
+		expectCode: 0,
+		expect: /imported 0 local memory file\(s\); 1 conflict\(s\)/,
+		pre: (_project, claude) => local(claude, "learning_shared_seed.md", "My divergent copy.\n"),
+	},
+	{
+		name: "audited: twenty-one previously deleted files straddle the reason cap",
+		expectCode: 0,
+		expect: /previously-deleted file\(s\) held back/,
+		seed: (clone) => {
+			for (let i = 0; i < 21; i++) {
+				writeFileSync(join(clone, "memories", `learning_gone_${String(i).padStart(2, "0")}.md`), "was\n");
+			}
+			git(clone, "add", "-A");
+			git(clone, "commit", "-qm", "add many");
+			for (let i = 0; i < 21; i++) rmSync(join(clone, "memories", `learning_gone_${String(i).padStart(2, "0")}.md`));
+			git(clone, "add", "-A");
+			git(clone, "commit", "-qm", "remove many");
+			git(clone, "push", "-q");
+		},
+		pre: (_project, claude) => {
+			for (let i = 0; i < 21; i++) local(claude, `learning_gone_${String(i).padStart(2, "0")}.md`, "stale\n");
+		},
+	},
+	{
+		name: "audited: a clone failure propagates git's exit status",
+		expectCode: 128,
+		skipAsRoot: true,
+		pre: (_project, claude) => chmodSync(claude, 0o500),
+	},
+	{
+		name: "audited: a trailing slash on the project path is not normalised away",
+		expectCode: 0,
+		trailingSlash: true,
+	},
+];
+
+describe("audited configure edges — behaviour is pinned", () => {
+	const root = process.getuid?.() === 0;
+	for (const fx of audited) {
+		// A read-only directory does not stop root, so that fixture proves nothing there.
+		test(fx.name, { skip: fx.skipAsRoot === true && root }, () => assertParity(fx));
+	}
+});
+
+const unchecked: readonly ConfigureFixture[] = [
+	{
+		// A fresh machine has no git identity, which is exactly when configureProject first runs.
+		name: "unchecked: a failed migration commit is not reported as a push",
+		expectCode: 128,
+		expect: /Migration: imported 1 local memory file\(s\)/,
+		env: {
+			GIT_CONFIG_GLOBAL: "/dev/null",
+			GIT_CONFIG_SYSTEM: "/dev/null",
+			GIT_AUTHOR_NAME: "",
+			GIT_AUTHOR_EMAIL: "",
+			GIT_COMMITTER_NAME: "",
+			GIT_COMMITTER_EMAIL: "",
+		},
+		pre: (_project, claude) => local(claude, "learning_mine_own.md"),
+	},
+	{
+		name: "unchecked: a dangling symlink is skipped, not fatal",
+		expectCode: 0,
+		expect: /Migration: imported 1 local memory file\(s\)/,
+		pre: (_project, claude) => {
+			local(claude, "learning_mine_own.md");
+			symlinkSync("/nonexistent/target.md", join(claude, "memories", "learning_dangling_link.md"));
+		},
+	},
+];
+
+describe("unchecked git results — behaviour is pinned", () => {
+	for (const fx of unchecked) test(fx.name, () => assertParity(fx));
+});
+
+describe("configure-memories — deliberate fixes to defects in the bash", () => {
+	test("an unset MCS_PROJECT_PATH is refused rather than resolved against the filesystem root", () => {
+		// The bash built "$MCS_PROJECT_PATH/.claude/..." by concatenation, so an empty
+		// value produced "/.claude/..." and failed deep inside git clone. Falling back
+		// to cwd would be worse: configure would set up whatever directory you stood in.
+		const r = runConfigure({ name: "unset project path", env: { MCS_PROJECT_PATH: "" } });
+		assert.equal(r.code, 1, "an unusable project path must fail fast");
+		assert.match(r.stderr, /MCS_PROJECT_PATH is not set/);
+		assert.equal(r.stdout, "", "nothing is reported as done");
+	});
+
+	test("a bootstrap install against a branch with no memories reports success", () => {
+		const r = runConfigure({ name: "bootstrap", emptyRemote: true });
+		assert.equal(r.code, 0, "a first install is not a failure");
+		assert.match(r.stdout, /Done\. 0 memory file\(s\) available at/);
+	});
+});
diff --git a/tests/differential.test.ts b/tests/differential.test.ts
new file mode 100644
index 0000000..c61cae9
--- /dev/null
+++ b/tests/differential.test.ts
@@ -0,0 +1,957 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { git, memory, readGolden, rejectAllPushes, runHook, type Fixture, type RunResult } from "./harness.ts";
+
+
+/**
+ * Behaviour is pinned to tests/golden/, recorded from the bash implementation
+ * this pack replaced and verified against it fixture by fixture before the bash
+ * was removed. A drift here is a change in what the pack does, not a stale test.
+ */
+const ABORT = /^\w+: aborted.*$/m;
+
+function check(name: string, actual: RunResult, expect?: RegExp, abortsDiffer = false): void {
+	const golden = readGolden(name);
+	assert.ok(golden, `no golden recorded for "${name}"`);
+	assert.equal(actual.stdout, golden.stdout, `stdout drifted from recorded behaviour for "${name}"`);
+	assert.equal(actual.code, golden.code, `exit code drifted for "${name}"`);
+	if (abortsDiffer) {
+		assert.match(golden.stderr, ABORT, `"${name}" claims an abort deviation the recording does not show`);
+		assert.match(actual.stderr, ABORT, `"${name}" should still report the abort`);
+		assert.equal(actual.stderr.replace(ABORT, ""), golden.stderr.replace(ABORT, ""), `stderr drifted outside the abort line for "${name}"`);
+	} else {
+		assert.equal(actual.stderr, golden.stderr, `stderr drifted from recorded behaviour for "${name}"`);
+	}
+	assert.equal(actual.git, golden.git, `resulting state drifted for "${name}"\ngolden:\n${golden.git}\n\nactual:\n${actual.git}`);
+	// A fixture where nothing happens passes vacuously, so pin what was recorded.
+	if (expect) assert.match(golden.stdout + golden.stderr, expect, `fixture "${name}" never exercised what it claims to`);
+}
+
+function assertParity(fx: Fixture): void {
+	check(fx.name, runHook(fx), fx.expect, fx.abortsDiffer);
+}
+
+const announce: readonly Fixture[] = [
+	{
+		name: "announce: review mode, well-named memory write",
+		expect: /"hookEventName": "PostToolUse"/,
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: { file_path: "/p/.claude/memories/learning_a_b.md" } }),
+	},
+	{
+		name: "announce: auto mode is silent",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		stdin: JSON.stringify({ tool_input: { file_path: "/p/.claude/memories/learning_a_b.md" } }),
+	},
+	{
+		name: "announce: unset mode is silent",
+		hook: "announce",
+		stdin: JSON.stringify({ tool_input: { file_path: "/p/.claude/memories/learning_a_b.md" } }),
+	},
+	{
+		name: "announce: unknown mode is silent",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "banana" },
+		stdin: JSON.stringify({ tool_input: { file_path: "/p/.claude/memories/learning_a_b.md" } }),
+	},
+	{
+		name: "announce: decision_ prefix also matches",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: { file_path: "/p/.claude/memories/decision_x_y.md" } }),
+	},
+	{
+		name: "announce: name with a space is rejected",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: { file_path: "/p/.claude/memories/learning_foo bar.md" } }),
+	},
+	{
+		name: "announce: path outside .claude/memories is rejected",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: { file_path: "/p/notes/learning_a_b.md" } }),
+	},
+	{
+		name: "announce: nested prefix path still matches",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: { file_path: "/deep/nest/.claude/memories/learning_a_b.md" } }),
+	},
+	{
+		name: "announce: wrong prefix is rejected",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: { file_path: "/p/.claude/memories/scratch_a_b.md" } }),
+	},
+	{
+		name: "announce: non-md extension is rejected",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: { file_path: "/p/.claude/memories/learning_a_b.txt" } }),
+	},
+	{
+		name: "announce: missing file_path",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: {} }),
+	},
+	{
+		name: "announce: non-string file_path",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: { file_path: 123 } }),
+	},
+	{
+		name: "announce: empty stdin",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: "",
+	},
+	{
+		name: "announce: malformed stdin",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: "not json at all",
+	},
+	{
+		name: "announce: a path containing a quote",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: JSON.stringify({ tool_input: { file_path: '/p/"q"/.claude/memories/learning_a_b.md' } }),
+	},
+];
+
+describe("announce — behaviour is pinned", () => {
+	for (const fx of announce) test(fx.name, () => assertParity(fx));
+});
+
+const pull: readonly Fixture[] = [
+	{ name: "pull: clean tree, auto", hook: "pull", env: { MEMORIES_AUTOPUSH_MODE: "auto" } },
+	{ name: "pull: clean tree, review", hook: "pull", env: { MEMORIES_AUTOPUSH_MODE: "review" } },
+	{
+		name: "pull: untracked memory, auto reports lingering state",
+		expect: /lingering state/,
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => memory(repo, "learning_pending_one.md"),
+	},
+	{
+		name: "pull: untracked memory, review reports awaiting review",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_pending_one.md"),
+	},
+	{
+		name: "pull: two untracked memories pluralise the same way",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			memory(repo, "learning_pending_one.md");
+			memory(repo, "learning_pending_two.md");
+		},
+	},
+	{
+		name: "pull: unpushed commit only",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			memory(repo, "learning_committed_x.md");
+			git(repo, "add", "-A");
+			git(repo, "commit", "-qm", "local only");
+		},
+	},
+	{
+		name: "pull: uncommitted and unpushed together",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			memory(repo, "learning_committed_x.md");
+			git(repo, "add", "-A");
+			git(repo, "commit", "-qm", "local only");
+			memory(repo, "learning_dirty_y.md");
+		},
+	},
+	{
+		name: "pull: no upstream configured",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			git(repo, "branch", "--unset-upstream");
+			memory(repo, "learning_pending_one.md");
+		},
+	},
+	{
+		name: "pull: unknown mode warns, clean tree",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "banana" },
+	},
+	{
+		name: "pull: unknown mode warning joins the pending message",
+		expect: /falling back to auto[^\n]*\\n\\nShared memories have lingering state/,
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "banana" },
+		setup: (repo) => memory(repo, "learning_pending_one.md"),
+	},
+	{
+		name: "pull: empty mode falls through to auto",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "" },
+		setup: (repo) => memory(repo, "learning_pending_one.md"),
+	},
+	{
+		name: "pull: review mode clears the dedupe state file",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => writeFileSync(join(repo, ".review-shown"), "deadbeef\n"),
+	},
+	{
+		name: "pull: auto mode leaves the dedupe state file alone",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => writeFileSync(join(repo, ".review-shown"), "deadbeef\n"),
+	},
+	{
+		name: "pull: missing checkout",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => rmSync(repo, { recursive: true, force: true }),
+	},
+	{ name: "pull: malformed stdin", hook: "pull", stdin: "not json", env: { MEMORIES_AUTOPUSH_MODE: "auto" } },
+	{
+		name: "pull: empty stdin still does the work",
+		hook: "pull",
+		stdin: "",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => memory(repo, "learning_pending_one.md"),
+	},
+	{
+		name: "pull: concatenated JSON stream is accepted",
+		hook: "pull",
+		stdin: '{"a":1} {"b":2}',
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => memory(repo, "learning_pending_one.md"),
+	},
+];
+
+describe("pull — behaviour is pinned", () => {
+	for (const fx of pull) test(fx.name, () => assertParity(fx));
+});
+
+const commit = (repo: string, msg: string) => {
+	git(repo, "add", "-A");
+	git(repo, "commit", "-qm", msg);
+};
+
+const autopush: readonly Fixture[] = [
+	{ name: "autopush: nothing pending, auto", hook: "autopush", env: { MEMORIES_AUTOPUSH_MODE: "auto" } },
+	{ name: "autopush: nothing pending, review", hook: "autopush", env: { MEMORIES_AUTOPUSH_MODE: "review" } },
+	{
+		name: "autopush: nothing pending clears stale review state",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => writeFileSync(join(repo, ".review-shown"), "stale\n"),
+	},
+	{
+		name: "autopush: auto commits and pushes a new memory",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", "A brand new lesson.\n"),
+	},
+	{
+		name: "autopush: auto pushes a modification",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => memory(repo, "learning_seed_topic.md", "Rewritten seed.\n"),
+	},
+	{
+		name: "autopush: auto parks a deletion",
+		expect: /deleted memory file\(s\) left for manual review/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => rmSync(join(repo, "memories", "learning_seed_topic.md")),
+	},
+	{
+		name: "autopush: auto parks deletions but still pushes an addition",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			rmSync(join(repo, "memories", "learning_seed_topic.md"));
+			memory(repo, "learning_added_alongside.md");
+		},
+	},
+	{
+		name: "autopush: full pushes the deletion",
+		expect: /^$/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "full" },
+		setup: (repo) => rmSync(join(repo, "memories", "learning_seed_topic.md")),
+	},
+	{
+		name: "autopush: full without deletions omits the suffix",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "full" },
+		setup: (repo) => memory(repo, "learning_new_thing.md"),
+	},
+	{
+		name: "autopush: guardrail blocks a badly named file in auto",
+		expect: /^Shared memories: skipping auto-push — unconventional filename\(s\):\n  - memories\/scratch\.md$/m,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => memory(repo, "scratch.md"),
+	},
+	{
+		name: "autopush: guardrail blocks in full too",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "full" },
+		setup: (repo) => memory(repo, "scratch.md"),
+	},
+	{
+		name: "autopush: guardrail blocks in review too",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "scratch.md"),
+	},
+	{
+		name: "autopush: guardrail lists several offenders",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			memory(repo, "scratch.md");
+			memory(repo, "wip notes.md");
+			memory(repo, "learning_ok_one.md");
+		},
+	},
+	{
+		name: "autopush: unknown mode falls through to auto silently",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "banana" },
+		setup: (repo) => memory(repo, "learning_new_thing.md"),
+	},
+	{
+		name: "autopush: unpushed commit only",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			memory(repo, "learning_committed_x.md");
+			commit(repo, "local only");
+		},
+	},
+	{
+		name: "autopush: no upstream configured",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			git(repo, "branch", "--unset-upstream");
+			memory(repo, "learning_new_thing.md");
+		},
+	},
+	{
+		name: "autopush: missing checkout",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => rmSync(repo, { recursive: true, force: true }),
+	},
+	{ name: "autopush: malformed stdin", hook: "autopush", stdin: "not json", env: { MEMORIES_AUTOPUSH_MODE: "auto" } },
+	{
+		name: "autopush: empty stdin still pushes",
+		hook: "autopush",
+		stdin: "",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => memory(repo, "learning_new_thing.md"),
+	},
+];
+
+describe("autopush — behaviour is pinned", () => {
+	for (const fx of autopush) test(fx.name, () => assertParity(fx));
+});
+
+const ESC = String.fromCharCode(27);
+
+const review: readonly Fixture[] = [
+	{
+		name: "review: a new file renders with its preview",
+		expect: /^\+ NEW  <file:\/\/.*learning_new_thing\.md>\n {7}"First real line of the memory\."$/m,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", "First real line of the memory.\nSecond line.\n"),
+	},
+	{
+		name: "review: preview skips leading blank and whitespace-only lines",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", "\n   \n\t\nActual content here.\n"),
+	},
+	{
+		name: "review: an empty file emits no preview line",
+		expect: /\+ NEW  <file:[^\n]*>\n(?!ceva)(?! {7}")/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", ""),
+	},
+	{
+		name: "review: a preview longer than 80 chars is truncated",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", `${"x".repeat(200)}\n`),
+	},
+	{
+		name: "review: ANSI escapes in a memory never reach the terminal",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", `safe${ESC}[31mRED text\n`),
+	},
+	{
+		name: "review: a bare carriage return is preserved, as the bash preserves it",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", "before\rafter\n"),
+	},
+	{
+		name: "review: a tab in the preview survives",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", "before\tafter\n"),
+	},
+	{
+		name: "review: a modification renders numstat",
+		expect: /^~ MOD  <file:\/\/.*>  \(\+3 -1\)$/m,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_seed_topic.md", "Line one.\nLine two.\nLine three.\n"),
+	},
+	{
+		name: "review: a deletion renders its relative timestamp",
+		expect: /^- DEL  memories\/learning_seed_topic\.md  \(last modified .+\)$/m,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => rmSync(join(repo, "memories", "learning_seed_topic.md")),
+	},
+	{
+		name: "review: new, modified and deleted together",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => {
+			memory(repo, "learning_extra_one.md", "Extra.\n");
+			commit(repo, "add extra");
+			git(repo, "push", "-q");
+			memory(repo, "learning_brand_new.md", "Brand new.\n");
+			memory(repo, "learning_seed_topic.md", "Modified seed.\n");
+			rmSync(join(repo, "memories", "learning_extra_one.md"));
+		},
+	},
+	{
+		name: "review: pending files plus an unpushed commit",
+		expect: /pending file\(s\) in memories\/ and 1 unpushed commit\(s\)/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => {
+			memory(repo, "learning_committed_x.md");
+			commit(repo, "local only");
+			memory(repo, "learning_brand_new.md", "Brand new.\n");
+		},
+	},
+	{
+		name: "review: unpushed commit with no dirty files",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => {
+			memory(repo, "learning_committed_x.md");
+			commit(repo, "local only");
+		},
+	},
+	{
+		name: "review: the same pending set is reported once",
+		expect: /^$/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		runs: 2,
+		setup: (repo) => memory(repo, "learning_new_thing.md", "A lesson.\n"),
+	},
+	{
+		name: "review: a stale stored hash reprints",
+		expect: /Shared memories \[review mode\]/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", "A lesson.\n"),
+		beforeEach: (repo) => writeFileSync(join(repo, ".review-shown"), "0000000000000000\n"),
+	},
+	{
+		name: "review: twenty-one deletions straddle the timestamp cap",
+		expect: /^- DEL  memories\/learning_bulk_20\.md$/m,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => {
+			for (let i = 0; i < 21; i++) memory(repo, `learning_bulk_${String(i).padStart(2, "0")}.md`, `Bulk ${i}.\n`);
+			commit(repo, "bulk");
+			git(repo, "push", "-q");
+			for (let i = 0; i < 21; i++) rmSync(join(repo, "memories", `learning_bulk_${String(i).padStart(2, "0")}.md`));
+		},
+	},
+];
+
+const reviewChange: Fixture = {
+	name: "review: adding a file after a report reprints",
+	expect: /2 pending file\(s\)/,
+	hook: "autopush",
+	env: { MEMORIES_AUTOPUSH_MODE: "review" },
+	runs: 2,
+	setup: (repo) => memory(repo, "learning_new_thing.md", "A lesson.\n"),
+	betweenRuns: (repo) => memory(repo, "learning_second_one.md", "Another lesson.\n"),
+};
+
+describe("review mode — behaviour is pinned", () => {
+	test(reviewChange.name, () => assertParity(reviewChange));
+	for (const fx of review) test(fx.name, () => assertParity(fx));
+});
+
+/** A second clone that pushes first, so our push is rejected as non-fast-forward. */
+const otherClonePushes = (repo: string, project: string, file: string, body: string) => {
+	const work = dirname(project);
+	const other = join(work, "other");
+	git(work, "clone", "-q", join(work, "remote.git"), other);
+	git(other, "config", "user.email", "o@example.com");
+	git(other, "config", "user.name", "Other");
+	writeFileSync(join(other, "memories", file), body);
+	git(other, "add", "-A");
+	git(other, "commit", "-qm", "from the other clone");
+	git(other, "push", "-q");
+};
+
+const push: readonly Fixture[] = [
+	{
+		name: "push: a rejected push rebases and retries into success",
+		expect: /^$/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo, project) => {
+			otherClonePushes(repo, project, "learning_theirs_one.md", "Theirs.\n");
+			memory(repo, "learning_ours_one.md", "Ours.\n");
+		},
+	},
+	{
+		name: "push: a rebase conflict pauses and aborts",
+		expect: /^Shared memories: auto-push paused — rebase conflict\. Resolve manually in \.claude\/\.memories-repo\/memories\.$/m,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo, project) => {
+			otherClonePushes(repo, project, "learning_seed_topic.md", "Their version of the seed.\n");
+			memory(repo, "learning_seed_topic.md", "Our version of the seed.\n");
+			commit(repo, "our conflicting edit");
+		},
+	},
+	{
+		name: "push: an unreachable remote reports auth or network",
+		expect: /^Shared memories: pull --rebase failed \(likely auth or network\)\. Will retry on next Stop\.$/m,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			memory(repo, "learning_ours_one.md", "Ours.\n");
+			commit(repo, "local only");
+			git(repo, "remote", "set-url", "origin", "/nonexistent/definitely-not-here.git");
+		},
+	},
+	{
+		name: "push: a zero attempt budget still tries once",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto", MEMORIES_PUSH_ATTEMPTS: "0" },
+		setup: (repo, project) => {
+			otherClonePushes(repo, project, "learning_theirs_one.md", "Theirs.\n");
+			memory(repo, "learning_ours_one.md", "Ours.\n");
+		},
+	},
+	{
+		name: "push: a non-integer attempt budget falls back to the default",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto", MEMORIES_PUSH_ATTEMPTS: "banana" },
+		setup: (repo, project) => {
+			otherClonePushes(repo, project, "learning_theirs_one.md", "Theirs.\n");
+			memory(repo, "learning_ours_one.md", "Ours.\n");
+		},
+	},
+];
+
+describe("push loop — behaviour is pinned", () => {
+	for (const fx of push) test(fx.name, () => assertParity(fx));
+});
+
+/** A remote that rejects every push, so the retry budget is spent rather than skipped. */
+const budgetFixture = (name: string, attempts: string | undefined, expect: RegExp): Fixture => ({
+	name,
+	expect,
+	hook: "autopush",
+	env: attempts === undefined
+		? { MEMORIES_AUTOPUSH_MODE: "auto" }
+		: { MEMORIES_AUTOPUSH_MODE: "auto", MEMORIES_PUSH_ATTEMPTS: attempts },
+	setup: (repo, project) => {
+		memory(repo, "learning_ours_one.md", "Ours.\n");
+		commit(repo, "local only");
+		rejectAllPushes(join(dirname(project), "remote.git"));
+	},
+});
+
+const budgets: readonly Fixture[] = [
+	budgetFixture("budget: zero is clamped to a single attempt", "0", /auto-push failed after 1 attempt\(s\)/),
+	budgetFixture("budget: an explicit small budget is honoured", "3", /auto-push failed after 3 attempt\(s\)/),
+	budgetFixture("budget: a non-integer falls back to twelve", "banana", /auto-push failed after 12 attempt\(s\)/),
+	budgetFixture("budget: unset falls back to twelve", undefined, /auto-push failed after 12 attempt\(s\)/),
+];
+
+describe("retry budget — behaviour is pinned", () => {
+	for (const fx of budgets) test(fx.name, () => assertParity(fx));
+});
+
+const audit: readonly Fixture[] = [
+	{
+		// grep's [[:space:]] includes CR; a CRLF file's "blank" line is not blank to /^[\t ]*$/.
+		name: "audit: a CRLF blank first line is skipped like bash skips it",
+		expect: /"Real content\r"/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", "\r\nReal content\r\n"),
+	},
+	{
+		// bash ${var:0:80} counts characters; JS slice counts UTF-16 code units.
+		name: "audit: an 80-character truncation counts characters, not code units",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", `${"é".repeat(100)}\n`),
+	},
+	{
+		name: "audit: astral characters truncate at the same point",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", `${"🌍".repeat(100)}\n`),
+	},
+	{
+		name: "audit: a memory path containing a space and a hash",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => memory(repo, "learning_new_thing.md", "Content.\n"),
+	},
+];
+
+describe("audit findings — behaviour is pinned", () => {
+	for (const fx of audit) test(fx.name, () => assertParity(fx));
+});
+
+/** The shared repo ships root-level files (README, LICENSE). Every git call is
+ *  scoped with `-- memories/` so they are visible but never swept into a commit. */
+const withDirtyRootFile = (repo: string) => {
+	writeFileSync(join(repo, "README.md"), "Shared memories repo.\n");
+	commit(repo, "add a root README");
+	git(repo, "push", "-q");
+	writeFileSync(join(repo, "README.md"), "Edited by a teammate.\n");
+};
+
+const pathspec: readonly Fixture[] = [
+	{
+		name: "pathspec: full mode leaves a dirty root file uncommitted",
+		expect: /^$/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "full" },
+		setup: (repo) => {
+			withDirtyRootFile(repo);
+			memory(repo, "learning_new_thing.md", "A lesson.\n");
+		},
+	},
+	{
+		name: "pathspec: auto mode leaves a dirty root file uncommitted",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			withDirtyRootFile(repo);
+			memory(repo, "learning_new_thing.md", "A lesson.\n");
+		},
+	},
+	{
+		name: "pathspec: a dirty root file does not trip the filename guardrail",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => withDirtyRootFile(repo),
+	},
+	{
+		name: "pathspec: review mode does not report a dirty root file",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => {
+			withDirtyRootFile(repo);
+			memory(repo, "learning_new_thing.md", "A lesson.\n");
+		},
+	},
+	{
+		name: "pathspec: SessionStart does not count a dirty root file as pending",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => withDirtyRootFile(repo),
+	},
+];
+
+describe("pathspec scoping — behaviour is pinned", () => {
+	for (const fx of pathspec) test(fx.name, () => assertParity(fx));
+});
+
+/** A teammate pushes while we are away; SessionStart is what brings it down. */
+const teammatePushes = (repo: string, project: string, file: string) => {
+	const work = dirname(project);
+	const other = join(work, "other");
+	git(work, "clone", "-q", join(work, "remote.git"), other);
+	git(other, "config", "user.email", "o@example.com");
+	git(other, "config", "user.name", "Other");
+	writeFileSync(join(other, "memories", file), "From a teammate.\n");
+	git(other, "add", "-A");
+	git(other, "commit", "-qm", "teammate memory");
+	git(other, "push", "-q");
+};
+
+const incoming: readonly Fixture[] = [
+	{
+		name: "incoming: SessionStart fast-forwards a teammate's memory",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo, project) => teammatePushes(repo, project, "learning_theirs_new.md"),
+	},
+	{
+		name: "incoming: a fast-forward alongside our own untracked memory",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo, project) => {
+			teammatePushes(repo, project, "learning_theirs_new.md");
+			memory(repo, "learning_ours_pending.md", "Ours, not yet pushed.\n");
+		},
+	},
+	{
+		name: "incoming: SessionStart does not fast-forward past a conflicting local commit",
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo, project) => {
+			teammatePushes(repo, project, "learning_theirs_new.md");
+			memory(repo, "learning_ours_own.md", "Ours.\n");
+			commit(repo, "our local commit");
+		},
+	},
+	{
+		name: "incoming: the Stop hook rebases onto a teammate's commit",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo, project) => {
+			teammatePushes(repo, project, "learning_theirs_new.md");
+			memory(repo, "learning_ours_own.md", "Ours.\n");
+		},
+	},
+];
+
+describe("incoming memories — behaviour is pinned", () => {
+	for (const fx of incoming) test(fx.name, () => assertParity(fx));
+});
+
+const edges: readonly Fixture[] = [
+	{
+		name: "edge: announce reads every value in a concatenated stream",
+		expect: /Memory file saved at \/p\/\.claude\/memories\/learning_a_b\.md\\n\/p\/\.claude\/memories\/learning_c_d\.md \(MEMORIES/,
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: '{"tool_input":{"file_path":"/p/.claude/memories/learning_a_b.md"}} {"tool_input":{"file_path":"/p/.claude/memories/learning_c_d.md"}}',
+	},
+	{
+		name: "edge: announce when only the second value carries a path",
+		expect: /learning_c_d\.md/,
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: '{"tool_input":{}} {"tool_input":{"file_path":"/p/.claude/memories/learning_c_d.md"}}',
+	},
+	{
+		// jq's `// empty` drops false, so it must not appear in the joined paths.
+		name: "edge: announce drops a false file_path from the stream",
+		expect: /Memory file saved at \/p\/\.claude\/memories\/learning_a_b\.md \(MEMORIES/,
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: '{"tool_input":{"file_path":false}} {"tool_input":{"file_path":"/p/.claude/memories/learning_a_b.md"}}',
+	},
+	{
+		// jq -r renders a non-string result as pretty JSON, not as a JS-style cast.
+		name: "edge: announce renders a non-string file_path the way jq does",
+		expect: /Memory file saved at \{\\n  \\"x\\": 1\\n\}\\n\/p\/\.claude/,
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: '{"tool_input":{"file_path":{"x":1}}} {"tool_input":{"file_path":"/p/.claude/memories/learning_a_b.md"}}',
+	},
+	{
+		name: "edge: announce strips a trailing newline the way $() did",
+		expect: /Memory file saved at \/p\/\.claude\/memories\/learning_a_b\.md \(MEMORIES/,
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: '{"tool_input":{"file_path":"/p/.claude/memories/learning_a_b.md\\n"}}',
+	},
+	{
+		name: "edge: an empty last result does not silence the nudge",
+		expect: /Memory file saved at \/p\/\.claude\/memories\/learning_a_b\.md \(MEMORIES/,
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: '{"tool_input":{"file_path":"/p/.claude/memories/learning_a_b.md"}} {"tool_input":{"file_path":""}}',
+	},
+	{
+		name: "edge: a locked index aborts the turn instead of reporting nothing",
+		abortsDiffer: true,
+		expect: /Unable to create .*index\.lock/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			memory(repo, "learning_new_thing.md", "A lesson.\n");
+			writeFileSync(join(repo, ".git", "index.lock"), "");
+		},
+	},
+	{
+		name: "edge: announce ignores a null file_path",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: '{"tool_input":{"file_path":null}}',
+	},
+	{
+		// jq neither aborts on an erroring value nor reports it once a later value
+		// succeeds, so the leading 42 is skipped and the path IS announced. The
+		// mirror-image fixture below is the silent one.
+		name: "edge: announce still reports a path after a leading scalar",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: '42 {"tool_input":{"file_path":"/p/.claude/memories/learning_a_b.md"}}',
+	},
+	{
+		// jq's status reflects the last value only, so a trailing scalar silences it.
+		name: "edge: announce is silent when a scalar follows a valid path",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: '{"tool_input":{"file_path":"/p/.claude/memories/learning_a_b.md"}} 42',
+	},
+	{
+		name: "edge: announce is silent when stdin is a bare scalar",
+		hook: "announce",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		stdin: "42",
+	},
+	{
+		name: "edge: review reports a staged rename as unclassified pending",
+		expect: /unclassified pending change\(s\) in memories\//,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => git(repo, "mv", "memories/learning_seed_topic.md", "memories/learning_seed_renamed.md"),
+	},
+	{
+		name: "edge: review on a detached HEAD with an unpushed commit",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => {
+			memory(repo, "learning_x_y.md");
+			commit(repo, "local");
+			git(repo, "checkout", "-q", "--detach");
+		},
+	},
+	{
+		name: "edge: a typechange to a symlink is unclassified pending",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "review" },
+		setup: (repo) => {
+			const p = join(repo, "memories", "learning_seed_topic.md");
+			rmSync(p);
+			symlinkSync("/etc/hostname", p);
+		},
+	},
+	{
+		name: "edge: a commit failure is reported and retried next Stop",
+		expect: /Shared memories: commit failed; will retry on next Stop\./,
+		hook: "autopush",
+		env: {
+			MEMORIES_AUTOPUSH_MODE: "auto",
+			GIT_CONFIG_GLOBAL: "/dev/null",
+			GIT_CONFIG_SYSTEM: "/dev/null",
+			GIT_AUTHOR_NAME: "",
+			GIT_COMMITTER_NAME: "",
+		},
+		setup: (repo) => {
+			git(repo, "config", "--unset", "user.email");
+			git(repo, "config", "--unset", "user.name");
+			memory(repo, "learning_x_y.md");
+		},
+	},
+	{
+		name: "edge: SessionStart survives a failed fast-forward",
+		expect: /lingering state/,
+		hook: "pull",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo, project) => {
+			teammatePushes(repo, project, "learning_theirs_a.md");
+			memory(repo, "learning_ours_b.md");
+			commit(repo, "ours");
+		},
+	},
+	{
+		name: "edge: a badly named DELETED file trips the guardrail",
+		expect: /unconventional filename\(s\):\n  - memories\/scratch\.md/,
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			writeFileSync(join(repo, "memories", "scratch.md"), "x\n");
+			commit(repo, "add scratch");
+			git(repo, "push", "-q");
+			rmSync(join(repo, "memories", "scratch.md"));
+		},
+	},
+	{
+		name: "edge: changes already staged in the index still commit",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo) => {
+			memory(repo, "learning_x_y.md");
+			git(repo, "add", "-A");
+		},
+	},
+	{
+		name: "edge: a dangling memories symlink does not stop the push",
+		hook: "autopush",
+		env: { MEMORIES_AUTOPUSH_MODE: "auto" },
+		setup: (repo, project) => {
+			rmSync(join(project, ".claude", "memories"));
+			symlinkSync(".memories-repo/nope", join(project, ".claude", "memories"));
+			memory(repo, "learning_x_y.md");
+		},
+	},
+];
+
+describe("audited edges — behaviour is pinned", () => {
+	for (const fx of edges) test(fx.name, () => assertParity(fx));
+});
+
+/**
+ * Asserted directly rather than pinned to a golden, and deliberately so.
+ *
+ * Every golden in this directory is a recording of the bash, and the bash is
+ * gone, so a hand-written file here would claim to be a recording it is not.
+ * The more durable reason is what a golden would add over these assertions:
+ * git's own error prose for a broken pushurl, byte for byte. Five goldens
+ * already quote git's English and that is this suite's known fragility --
+ * a translated or reworded git breaks them. Not a property worth extending
+ * to a sixth for a branch whose contract is an exit code.
+ */
+describe("push failures are classified by exit code, not message text", () => {
+	test("a broken pushurl reaches the non-rejection branch", () => {
+		const r = runHook({
+			name: "internal: a broken pushurl is not a rejected update",
+			hook: "autopush",
+			env: { MEMORIES_AUTOPUSH_MODE: "full" },
+			setup: (repo) => {
+				// A valid fetch url with a broken pushurl: `pull --rebase` one line
+				// earlier still exits 0, so the loop reaches the push, and the push
+				// exits 128 rather than the 1 that means the remote rejected it.
+				git(repo, "config", "remote.origin.pushurl", "/nonexistent/remote.git");
+				memory(repo, "learning_new_thing.md", "A lesson.\n");
+			},
+		});
+		assert.match(r.stdout, /auto-push failed \(not a rejected update/);
+		assert.doesNotMatch(r.stdout, /after \d+ attempt/, "a non-rejection must not spend the retry budget");
+		assert.equal(r.code, 0);
+	});
+});
diff --git a/tests/epipe.test.ts b/tests/epipe.test.ts
new file mode 100644
index 0000000..80ca584
--- /dev/null
+++ b/tests/epipe.test.ts
@@ -0,0 +1,49 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { chmodSync, cpSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { makeProject } from "./harness.ts";
+
+const REPO = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** Runs a hook with its stdout reader gone before it writes: the EPIPE case. */
+function runWithNoReader(hook: string, env: Record<string, string>, stdin: string) {
+	const { root, project } = makeProject();
+	const hooks = join(project, ".claude", "hooks", "shared-memories");
+	mkdirSync(hooks, { recursive: true });
+	cpSync(join(REPO, "runtime", hook), join(hooks, hook));
+	chmodSync(join(hooks, hook), 0o755);
+	cpSync(join(REPO, "runtime", "lib"), join(hooks, "lib"), { recursive: true });
+
+	return new Promise<{ code: number | null; signal: string | null; stderr: string }>((resolve) => {
+		const child = spawn(join(hooks, hook), [], {
+			cwd: project,
+			env: { ...process.env, ...env },
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+		let stderr = "";
+		child.stderr.setEncoding("utf8");
+		child.stderr.on("data", (d) => (stderr += d));
+		child.stdout.destroy();
+		child.stdin.end(stdin);
+		child.on("close", (code, signal) => {
+			rmSync(root, { recursive: true, force: true });
+			resolve({ code, signal, stderr });
+		});
+	});
+}
+
+describe("a hook whose reader has gone away", () => {
+	test("announce still exits 0 and reports no stack", async () => {
+		const r = await runWithNoReader(
+			"announce.mts",
+			{ MEMORIES_AUTOPUSH_MODE: "review" },
+			JSON.stringify({ tool_input: { file_path: "/p/.claude/memories/learning_a_b.md" } }),
+		);
+		assert.equal(r.signal, null, "the hook must not die on SIGPIPE");
+		assert.equal(r.code, 0);
+		assert.doesNotMatch(r.stderr, /EPIPE/, "EPIPE must not surface as a failure");
+	});
+});
diff --git a/tests/golden/a-regular-file-at-the-memories-path-is-refused.json b/tests/golden/a-regular-file-at-the-memories-path-is-refused.json
new file mode 100644
index 0000000..c4e4e61
--- /dev/null
+++ b/tests/golden/a-regular-file-at-the-memories-path-is-refused.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "<TMP>/work/project/.claude/memories exists but is not a directory or symlink; refusing to touch it.\n",
+  "code": 0,
+  "git": "memories"
+}
diff --git a/tests/golden/an-unresolved-repo-url-skips-quietly.json b/tests/golden/an-unresolved-repo-url-skips-quietly.json
new file mode 100644
index 0000000..fb24a53
--- /dev/null
+++ b/tests/golden/an-unresolved-repo-url-skips-quietly.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "MEMORIES_REPO_URL not resolved; skipping memories clone.\n",
+  "code": 0,
+  "git": ""
+}
diff --git a/tests/golden/announce-a-path-containing-a-quote.json b/tests/golden/announce-a-path-containing-a-quote.json
new file mode 100644
index 0000000..b1a04d4
--- /dev/null
+++ b/tests/golden/announce-a-path-containing-a-quote.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /p/\\\"q\\\"/.claude/memories/learning_a_b.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-auto-mode-is-silent.json b/tests/golden/announce-auto-mode-is-silent.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-auto-mode-is-silent.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-decision-prefix-also-matches.json b/tests/golden/announce-decision-prefix-also-matches.json
new file mode 100644
index 0000000..adeb14d
--- /dev/null
+++ b/tests/golden/announce-decision-prefix-also-matches.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /p/.claude/memories/decision_x_y.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-empty-stdin.json b/tests/golden/announce-empty-stdin.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-empty-stdin.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-malformed-stdin.json b/tests/golden/announce-malformed-stdin.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-malformed-stdin.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-missing-file-path.json b/tests/golden/announce-missing-file-path.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-missing-file-path.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-name-with-a-space-is-rejected.json b/tests/golden/announce-name-with-a-space-is-rejected.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-name-with-a-space-is-rejected.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-nested-prefix-path-still-matches.json b/tests/golden/announce-nested-prefix-path-still-matches.json
new file mode 100644
index 0000000..e8e6fb1
--- /dev/null
+++ b/tests/golden/announce-nested-prefix-path-still-matches.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /deep/nest/.claude/memories/learning_a_b.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-non-md-extension-is-rejected.json b/tests/golden/announce-non-md-extension-is-rejected.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-non-md-extension-is-rejected.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-non-string-file-path.json b/tests/golden/announce-non-string-file-path.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-non-string-file-path.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-path-outside-claude-memories-is-rejected.json b/tests/golden/announce-path-outside-claude-memories-is-rejected.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-path-outside-claude-memories-is-rejected.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-review-mode-well-named-memory-write.json b/tests/golden/announce-review-mode-well-named-memory-write.json
new file mode 100644
index 0000000..2da0719
--- /dev/null
+++ b/tests/golden/announce-review-mode-well-named-memory-write.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /p/.claude/memories/learning_a_b.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-unknown-mode-is-silent.json b/tests/golden/announce-unknown-mode-is-silent.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-unknown-mode-is-silent.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-unset-mode-is-silent.json b/tests/golden/announce-unset-mode-is-silent.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-unset-mode-is-silent.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/announce-wrong-prefix-is-rejected.json b/tests/golden/announce-wrong-prefix-is-rejected.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/announce-wrong-prefix-is-rejected.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/audit-a-crlf-blank-first-line-is-skipped-like-bash-skips-it.json b/tests/golden/audit-a-crlf-blank-first-line-is-skipped-like-bash-skips-it.json
new file mode 100644
index 0000000..6f0bc7c
--- /dev/null
+++ b/tests/golden/audit-a-crlf-blank-first-line-is-skipped-like-bash-skips-it.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"Real content\r\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/audit-a-memory-path-containing-a-space-and-a-hash.json b/tests/golden/audit-a-memory-path-containing-a-space-and-a-hash.json
new file mode 100644
index 0000000..0579998
--- /dev/null
+++ b/tests/golden/audit-a-memory-path-containing-a-space-and-a-hash.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"Content.\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/audit-an-80-character-truncation-counts-characters-not-code-units.json b/tests/golden/audit-an-80-character-truncation-counts-characters-not-code-units.json
new file mode 100644
index 0000000..5411ab5
--- /dev/null
+++ b/tests/golden/audit-an-80-character-truncation-counts-characters-not-code-units.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"éééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééééé\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/audit-astral-characters-truncate-at-the-same-point.json b/tests/golden/audit-astral-characters-truncate-at-the-same-point.json
new file mode 100644
index 0000000..e31bc09
--- /dev/null
+++ b/tests/golden/audit-astral-characters-truncate-at-the-same-point.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍🌍\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/audited-a-bootstrap-branch-with-no-memories-tree-exits-2-without-done.json b/tests/golden/audited-a-bootstrap-branch-with-no-memories-tree-exits-2-without-done.json
new file mode 100644
index 0000000..9ee30e3
--- /dev/null
+++ b/tests/golden/audited-a-bootstrap-branch-with-no-memories-tree-exits-2-without-done.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Cloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 2,
+  "git": ".memories-repo memories"
+}
diff --git a/tests/golden/audited-a-clone-failure-propagates-git-s-exit-status.json b/tests/golden/audited-a-clone-failure-propagates-git-s-exit-status.json
new file mode 100644
index 0000000..b07f392
--- /dev/null
+++ b/tests/golden/audited-a-clone-failure-propagates-git-s-exit-status.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Cloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\n",
+  "stderr": "fatal: could not create work tree dir '<TMP>/work/project/.claude/.memories-repo': Permission denied\n",
+  "code": 128,
+  "git": ""
+}
diff --git a/tests/golden/audited-a-dangling-symlink-with-no-checkout-is-replaced.json b/tests/golden/audited-a-dangling-symlink-with-no-checkout-is-replaced.json
new file mode 100644
index 0000000..2410219
--- /dev/null
+++ b/tests/golden/audited-a-dangling-symlink-with-no-checkout-is-replaced.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Cloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nDone. 1 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/audited-a-dotted-md-file-migrates-but-is-not-counted.json b/tests/golden/audited-a-dotted-md-file-migrates-but-is-not-counted.json
new file mode 100644
index 0000000..0e4f697
--- /dev/null
+++ b/tests/golden/audited-a-dotted-md-file-migrates-but-is-not-counted.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 3 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 3 local memory file(s); 0 conflict(s) (shared version kept).\nPushed migrated memories to the shared branch.\nNote: these migrated files don't match the naming convention and were left untracked:\n  - memories/.hidden\n  - memories/.hidden.md\nRename them to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so they can be shared with the team.\nDone. 2 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-repo memories\n.hidden .hidden.md learning_mine_own.md learning_shared_seed.md"
+}
diff --git a/tests/golden/audited-a-subdirectory-in-the-migration-backup-is-left-behind.json b/tests/golden/audited-a-subdirectory-in-the-migration-backup-is-left-behind.json
new file mode 100644
index 0000000..82d855e
--- /dev/null
+++ b/tests/golden/audited-a-subdirectory-in-the-migration-backup-is-left-behind.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 2 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 1 local memory file(s); 0 conflict(s) (shared version kept); 0 previously-deleted file(s) held back.\n  Kept at <TMP>/work/project/.claude/.memories-migration-<TS> for review.\nPushed migrated memories to the shared branch.\nDone. 2 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-migration-<TS> .memories-repo memories\nlearning_mine_own.md learning_shared_seed.md"
+}
diff --git a/tests/golden/audited-a-symlink-to-a-non-git-directory-beside-a-live-checkout-is-relinked.json b/tests/golden/audited-a-symlink-to-a-non-git-directory-beside-a-live-checkout-is-relinked.json
new file mode 100644
index 0000000..d6a99a6
--- /dev/null
+++ b/tests/golden/audited-a-symlink-to-a-non-git-directory-beside-a-live-checkout-is-relinked.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Memories checkout present, (re)linking <TMP>/work/project/.claude/memories → .memories-repo/memories...\nDone. 1 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/audited-a-trailing-slash-on-the-project-path-is-not-normalised-away.json b/tests/golden/audited-a-trailing-slash-on-the-project-path-is-not-normalised-away.json
new file mode 100644
index 0000000..c826bb0
--- /dev/null
+++ b/tests/golden/audited-a-trailing-slash-on-the-project-path-is-not-normalised-away.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Cloning shared memories (branch 'main', sparse) into <TMP>/work/project//.claude/.memories-repo...\nDone. 1 memory file(s) available at <TMP>/work/project//.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project//.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/audited-every-migrated-file-conflicting-imports-nothing.json b/tests/golden/audited-every-migrated-file-conflicting-imports-nothing.json
new file mode 100644
index 0000000..83626e6
--- /dev/null
+++ b/tests/golden/audited-every-migrated-file-conflicting-imports-nothing.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 1 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 0 local memory file(s); 1 conflict(s) (shared version kept); 0 previously-deleted file(s) held back.\n  Kept at <TMP>/work/project/.claude/.memories-migration-<TS> for review.\nDone. 1 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-migration-<TS> .memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/audited-twenty-one-previously-deleted-files-straddle-the-reason-cap.json b/tests/golden/audited-twenty-one-previously-deleted-files-straddle-the-reason-cap.json
new file mode 100644
index 0000000..d55a986
--- /dev/null
+++ b/tests/golden/audited-twenty-one-previously-deleted-files-straddle-the-reason-cap.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 21 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 0 local memory file(s); 0 conflict(s) (shared version kept); 21 previously-deleted file(s) held back.\n  Kept at <TMP>/work/project/.claude/.memories-migration-<TS> for review.\n\nHeld back 21 file(s) previously deleted from the shared repo:\n  - learning_gone_00.md\n      deleted by <SHA> remove many\n  - learning_gone_01.md\n      deleted by <SHA> remove many\n  - learning_gone_02.md\n      deleted by <SHA> remove many\n  - learning_gone_03.md\n      deleted by <SHA> remove many\n  - learning_gone_04.md\n      deleted by <SHA> remove many\n  - learning_gone_05.md\n      deleted by <SHA> remove many\n  - learning_gone_06.md\n      deleted by <SHA> remove many\n  - learning_gone_07.md\n      deleted by <SHA> remove many\n  - learning_gone_08.md\n      deleted by <SHA> remove many\n  - learning_gone_09.md\n      deleted by <SHA> remove many\n  - learning_gone_10.md\n      deleted by <SHA> remove many\n  - learning_gone_11.md\n      deleted by <SHA> remove many\n  - learning_gone_12.md\n      deleted by <SHA> remove many\n  - learning_gone_13.md\n      deleted by <SHA> remove many\n  - learning_gone_14.md\n      deleted by <SHA> remove many\n  - learning_gone_15.md\n      deleted by <SHA> remove many\n  - learning_gone_16.md\n      deleted by <SHA> remove many\n  - learning_gone_17.md\n      deleted by <SHA> remove many\n  - learning_gone_18.md\n      deleted by <SHA> remove many\n  - learning_gone_19.md\n      deleted by <SHA> remove many\n  - learning_gone_20.md\n\nSomeone removed these deliberately, so they were not re-imported or pushed.\nTo re-add one anyway: cp '<TMP>/work/project/.claude/.memories-migration-<TS>/<file>' '<TMP>/work/project/.claude/memories/<file>'\nDone. 1 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-migration-<TS> .memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/autopush-auto-commits-and-pushes-a-new-memory.json b/tests/golden/autopush-auto-commits-and-pushes-a-new-memory.json
new file mode 100644
index 0000000..7677c9d
--- /dev/null
+++ b/tests/golden/autopush-auto-commits-and-pushes-a-new-memory.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | seed\ntracked-all: memories/learning_new_thing.md | memories/learning_seed_topic.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_new_thing.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: auto: memories from <HOST> <DATE> | seed\nremote-files: memories/learning_new_thing.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-auto-parks-a-deletion.json b/tests/golden/autopush-auto-parks-a-deletion.json
new file mode 100644
index 0000000..87e570e
--- /dev/null
+++ b/tests/golden/autopush-auto-parks-a-deletion.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: 1 deleted memory file(s) left for manual review (not auto-pushed):\n  - memories/learning_seed_topic.md\nIf intentional (e.g. after memory-audit), approve them:\n  /approve-memories audit cleanup\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: D memories/learning_seed_topic.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: D memories/learning_seed_topic.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: \nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-auto-parks-deletions-but-still-pushes-an-addition.json b/tests/golden/autopush-auto-parks-deletions-but-still-pushes-an-addition.json
new file mode 100644
index 0000000..1f2fa48
--- /dev/null
+++ b/tests/golden/autopush-auto-parks-deletions-but-still-pushes-an-addition.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: 1 deleted memory file(s) left for manual review (not auto-pushed):\n  - memories/learning_seed_topic.md\nIf intentional (e.g. after memory-audit), approve them:\n  /approve-memories audit cleanup\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: D memories/learning_seed_topic.md\nlog-all: auto: memories from <HOST> <DATE> | seed\ntracked-all: memories/learning_added_alongside.md | memories/learning_seed_topic.md\nstatus: D memories/learning_seed_topic.md\nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_added_alongside.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_added_alongside.md\nremote-log: auto: memories from <HOST> <DATE> | seed\nremote-files: memories/learning_added_alongside.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-auto-pushes-a-modification.json b/tests/golden/autopush-auto-pushes-a-modification.json
new file mode 100644
index 0000000..a1d205a
--- /dev/null
+++ b/tests/golden/autopush-auto-pushes-a-modification.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: auto: memories from <HOST> <DATE> | seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-empty-stdin-still-pushes.json b/tests/golden/autopush-empty-stdin-still-pushes.json
new file mode 100644
index 0000000..7677c9d
--- /dev/null
+++ b/tests/golden/autopush-empty-stdin-still-pushes.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | seed\ntracked-all: memories/learning_new_thing.md | memories/learning_seed_topic.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_new_thing.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: auto: memories from <HOST> <DATE> | seed\nremote-files: memories/learning_new_thing.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-full-pushes-the-deletion.json b/tests/golden/autopush-full-pushes-the-deletion.json
new file mode 100644
index 0000000..5689888
--- /dev/null
+++ b/tests/golden/autopush-full-pushes-the-deletion.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> (includes deletions) | seed\ntracked-all: \nstatus: \nlog: auto: memories from <HOST> <DATE> (includes deletions) | seed\nupstream: origin/main\nunpushed: 0\ntracked: \nreview-shown: absent\nworktree: \nremote-log: auto: memories from <HOST> <DATE> (includes deletions) | seed\nremote-files: "
+}
diff --git a/tests/golden/autopush-full-without-deletions-omits-the-suffix.json b/tests/golden/autopush-full-without-deletions-omits-the-suffix.json
new file mode 100644
index 0000000..7677c9d
--- /dev/null
+++ b/tests/golden/autopush-full-without-deletions-omits-the-suffix.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | seed\ntracked-all: memories/learning_new_thing.md | memories/learning_seed_topic.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_new_thing.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: auto: memories from <HOST> <DATE> | seed\nremote-files: memories/learning_new_thing.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-guardrail-blocks-a-badly-named-file-in-auto.json b/tests/golden/autopush-guardrail-blocks-a-badly-named-file-in-auto.json
new file mode 100644
index 0000000..cd13c30
--- /dev/null
+++ b/tests/golden/autopush-guardrail-blocks-a-badly-named-file-in-auto.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: skipping auto-push — unconventional filename(s):\n  - memories/scratch.md\nRename to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so the guardrail accepts them.\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/scratch.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/scratch.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md scratch.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-guardrail-blocks-in-full-too.json b/tests/golden/autopush-guardrail-blocks-in-full-too.json
new file mode 100644
index 0000000..cd13c30
--- /dev/null
+++ b/tests/golden/autopush-guardrail-blocks-in-full-too.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: skipping auto-push — unconventional filename(s):\n  - memories/scratch.md\nRename to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so the guardrail accepts them.\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/scratch.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/scratch.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md scratch.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-guardrail-blocks-in-review-too.json b/tests/golden/autopush-guardrail-blocks-in-review-too.json
new file mode 100644
index 0000000..cd13c30
--- /dev/null
+++ b/tests/golden/autopush-guardrail-blocks-in-review-too.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: skipping auto-push — unconventional filename(s):\n  - memories/scratch.md\nRename to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so the guardrail accepts them.\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/scratch.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/scratch.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md scratch.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-guardrail-lists-several-offenders.json b/tests/golden/autopush-guardrail-lists-several-offenders.json
new file mode 100644
index 0000000..cd08771
--- /dev/null
+++ b/tests/golden/autopush-guardrail-lists-several-offenders.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: skipping auto-push — unconventional filename(s):\n  - memories/scratch.md\n  - memories/wip notes.md\nRename to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so the guardrail accepts them.\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? \"memories/wip notes.md\" | ?? memories/learning_ok_one.md | ?? memories/scratch.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? \"memories/wip notes.md\" | ?? memories/learning_ok_one.md | ?? memories/scratch.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_ok_one.md learning_seed_topic.md scratch.md wip notes.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-malformed-stdin.json b/tests/golden/autopush-malformed-stdin.json
new file mode 100644
index 0000000..3b58e99
--- /dev/null
+++ b/tests/golden/autopush-malformed-stdin.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "memories_autopush: stdin is not valid JSON; skipping\n",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-missing-checkout.json b/tests/golden/autopush-missing-checkout.json
new file mode 100644
index 0000000..e72e84b
--- /dev/null
+++ b/tests/golden/autopush-missing-checkout.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "memories_autopush: <TMP>/work/project/.claude/.memories-repo is not a git worktree; skipping (project_root=<TMP>/work/project)\n",
+  "code": 0,
+  "git": "status-all: \nlog-all: \ntracked-all: \nstatus: \nlog: \nupstream: (none)\nunpushed: 0\ntracked: \nreview-shown: absent\nworktree: \nremote-log: \nremote-files: "
+}
diff --git a/tests/golden/autopush-no-upstream-configured.json b/tests/golden/autopush-no-upstream-configured.json
new file mode 100644
index 0000000..3c3c14d
--- /dev/null
+++ b/tests/golden/autopush-no-upstream-configured.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | seed\ntracked-all: memories/learning_new_thing.md | memories/learning_seed_topic.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: (none)\nunpushed: 0\ntracked: memories/learning_new_thing.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-nothing-pending-auto.json b/tests/golden/autopush-nothing-pending-auto.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/autopush-nothing-pending-auto.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-nothing-pending-clears-stale-review-state.json b/tests/golden/autopush-nothing-pending-clears-stale-review-state.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/autopush-nothing-pending-clears-stale-review-state.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-nothing-pending-review.json b/tests/golden/autopush-nothing-pending-review.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/autopush-nothing-pending-review.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-unknown-mode-falls-through-to-auto-silently.json b/tests/golden/autopush-unknown-mode-falls-through-to-auto-silently.json
new file mode 100644
index 0000000..7677c9d
--- /dev/null
+++ b/tests/golden/autopush-unknown-mode-falls-through-to-auto-silently.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | seed\ntracked-all: memories/learning_new_thing.md | memories/learning_seed_topic.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_new_thing.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: auto: memories from <HOST> <DATE> | seed\nremote-files: memories/learning_new_thing.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/autopush-unpushed-commit-only.json b/tests/golden/autopush-unpushed-commit-only.json
new file mode 100644
index 0000000..7bba178
--- /dev/null
+++ b/tests/golden/autopush-unpushed-commit-only.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: local only | seed\ntracked-all: memories/learning_committed_x.md | memories/learning_seed_topic.md\nstatus: \nlog: local only | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_committed_x.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_committed_x.md learning_seed_topic.md\nremote-log: local only | seed\nremote-files: memories/learning_committed_x.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/budget-a-non-integer-falls-back-to-twelve.json b/tests/golden/budget-a-non-integer-falls-back-to-twelve.json
new file mode 100644
index 0000000..f22a647
--- /dev/null
+++ b/tests/golden/budget-a-non-integer-falls-back-to-twelve.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: auto-push failed after 12 attempt(s). Will retry on next Stop.\n  To <TMP>/work/remote.git\n ! [remote rejected] main -> main (pre-receive hook declined)\nerror: failed to push some refs to '<TMP>/work/remote.git'\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: local only | seed\ntracked-all: memories/learning_ours_one.md | memories/learning_seed_topic.md\nstatus: \nlog: local only | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_ours_one.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_ours_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/budget-an-explicit-small-budget-is-honoured.json b/tests/golden/budget-an-explicit-small-budget-is-honoured.json
new file mode 100644
index 0000000..cf43c31
--- /dev/null
+++ b/tests/golden/budget-an-explicit-small-budget-is-honoured.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: auto-push failed after 3 attempt(s). Will retry on next Stop.\n  To <TMP>/work/remote.git\n ! [remote rejected] main -> main (pre-receive hook declined)\nerror: failed to push some refs to '<TMP>/work/remote.git'\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: local only | seed\ntracked-all: memories/learning_ours_one.md | memories/learning_seed_topic.md\nstatus: \nlog: local only | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_ours_one.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_ours_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/budget-unset-falls-back-to-twelve.json b/tests/golden/budget-unset-falls-back-to-twelve.json
new file mode 100644
index 0000000..f22a647
--- /dev/null
+++ b/tests/golden/budget-unset-falls-back-to-twelve.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: auto-push failed after 12 attempt(s). Will retry on next Stop.\n  To <TMP>/work/remote.git\n ! [remote rejected] main -> main (pre-receive hook declined)\nerror: failed to push some refs to '<TMP>/work/remote.git'\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: local only | seed\ntracked-all: memories/learning_ours_one.md | memories/learning_seed_topic.md\nstatus: \nlog: local only | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_ours_one.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_ours_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/budget-zero-is-clamped-to-a-single-attempt.json b/tests/golden/budget-zero-is-clamped-to-a-single-attempt.json
new file mode 100644
index 0000000..26800a3
--- /dev/null
+++ b/tests/golden/budget-zero-is-clamped-to-a-single-attempt.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: auto-push failed after 1 attempt(s). Will retry on next Stop.\n  To <TMP>/work/remote.git\n ! [remote rejected] main -> main (pre-receive hook declined)\nerror: failed to push some refs to '<TMP>/work/remote.git'\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: local only | seed\ntracked-all: memories/learning_ours_one.md | memories/learning_seed_topic.md\nstatus: \nlog: local only | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_ours_one.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_ours_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/case-1-an-already-linked-setup-is-left-alone.json b/tests/golden/case-1-an-already-linked-setup-is-left-alone.json
new file mode 100644
index 0000000..7f7892d
--- /dev/null
+++ b/tests/golden/case-1-an-already-linked-setup-is-left-alone.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories already linked — leaving as-is.\n",
+  "stderr": "",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/case-2-a-badly-named-migrated-file-is-left-untracked.json b/tests/golden/case-2-a-badly-named-migrated-file-is-left-untracked.json
new file mode 100644
index 0000000..d0f89b6
--- /dev/null
+++ b/tests/golden/case-2-a-badly-named-migrated-file-is-left-untracked.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 2 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 2 local memory file(s); 0 conflict(s) (shared version kept).\nPushed migrated memories to the shared branch.\nNote: these migrated files don't match the naming convention and were left untracked:\n  - memories/scratch.md\nRename them to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so they can be shared with the team.\nDone. 3 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_mine_own.md learning_shared_seed.md scratch.md"
+}
diff --git a/tests/golden/case-2-a-migrated-non-markdown-file-is-not-counted-as-a-memory.json b/tests/golden/case-2-a-migrated-non-markdown-file-is-not-counted-as-a-memory.json
new file mode 100644
index 0000000..3a67069
--- /dev/null
+++ b/tests/golden/case-2-a-migrated-non-markdown-file-is-not-counted-as-a-memory.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 2 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 2 local memory file(s); 0 conflict(s) (shared version kept).\nPushed migrated memories to the shared branch.\nNote: these migrated files don't match the naming convention and were left untracked:\n  - memories/notes.txt\nRename them to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so they can be shared with the team.\nDone. 2 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_mine_own.md learning_shared_seed.md notes.txt"
+}
diff --git a/tests/golden/case-2-a-populated-memories-directory-migrates-and-pushes.json b/tests/golden/case-2-a-populated-memories-directory-migrates-and-pushes.json
new file mode 100644
index 0000000..b14a6a0
--- /dev/null
+++ b/tests/golden/case-2-a-populated-memories-directory-migrates-and-pushes.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 1 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 1 local memory file(s); 0 conflict(s) (shared version kept).\nPushed migrated memories to the shared branch.\nDone. 2 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_mine_own.md learning_shared_seed.md"
+}
diff --git a/tests/golden/case-2-a-previously-deleted-memory-is-held-back.json b/tests/golden/case-2-a-previously-deleted-memory-is-held-back.json
new file mode 100644
index 0000000..68d7f45
--- /dev/null
+++ b/tests/golden/case-2-a-previously-deleted-memory-is-held-back.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 1 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 0 local memory file(s); 0 conflict(s) (shared version kept); 1 previously-deleted file(s) held back.\n  Kept at <TMP>/work/project/.claude/.memories-migration-<TS> for review.\n\nHeld back 1 file(s) previously deleted from the shared repo:\n  - learning_curated_away.md\n      deleted by <SHA> remove it\n\nSomeone removed these deliberately, so they were not re-imported or pushed.\nTo re-add one anyway: cp '<TMP>/work/project/.claude/.memories-migration-<TS>/<file>' '<TMP>/work/project/.claude/memories/<file>'\nDone. 1 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-migration-<TS> .memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/case-2-an-empty-memories-directory-is-removed.json b/tests/golden/case-2-an-empty-memories-directory-is-removed.json
new file mode 100644
index 0000000..36e3d01
--- /dev/null
+++ b/tests/golden/case-2-an-empty-memories-directory-is-removed.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found empty <TMP>/work/project/.claude/memories — removing and proceeding with fresh setup.\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nDone. 1 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/case-2-the-shared-copy-wins-a-filename-conflict.json b/tests/golden/case-2-the-shared-copy-wins-a-filename-conflict.json
new file mode 100644
index 0000000..83626e6
--- /dev/null
+++ b/tests/golden/case-2-the-shared-copy-wins-a-filename-conflict.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 1 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 0 local memory file(s); 1 conflict(s) (shared version kept); 0 previously-deleted file(s) held back.\n  Kept at <TMP>/work/project/.claude/.memories-migration-<TS> for review.\nDone. 1 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-migration-<TS> .memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/case-3-a-live-checkout-with-no-symlink-is-relinked.json b/tests/golden/case-3-a-live-checkout-with-no-symlink-is-relinked.json
new file mode 100644
index 0000000..d6a99a6
--- /dev/null
+++ b/tests/golden/case-3-a-live-checkout-with-no-symlink-is-relinked.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Memories checkout present, (re)linking <TMP>/work/project/.claude/memories → .memories-repo/memories...\nDone. 1 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/case-4-a-non-checkout-at-the-repo-path-is-refused.json b/tests/golden/case-4-a-non-checkout-at-the-repo-path-is-refused.json
new file mode 100644
index 0000000..3d58bf5
--- /dev/null
+++ b/tests/golden/case-4-a-non-checkout-at-the-repo-path-is-refused.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "<TMP>/work/project/.claude/.memories-repo exists but is not a valid git checkout; refusing to touch it.\nDelete it manually and re-run `mcs sync` to re-clone.\n",
+  "code": 0,
+  "git": ".memories-repo"
+}
diff --git a/tests/golden/case-5-fresh-setup-clones-and-links.json b/tests/golden/case-5-fresh-setup-clones-and-links.json
new file mode 100644
index 0000000..2410219
--- /dev/null
+++ b/tests/golden/case-5-fresh-setup-clones-and-links.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Cloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nDone. 1 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-repo memories\nlearning_shared_seed.md"
+}
diff --git a/tests/golden/doctor-checkout-present-symlink-missing.json b/tests/golden/doctor-checkout-present-symlink-missing.json
new file mode 100644
index 0000000..29e1bc8
--- /dev/null
+++ b/tests/golden/doctor-checkout-present-symlink-missing.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories setup is unhealthy:\n  - symlink missing at <TMP>/work/project/.claude/memories (run 'mcs sync' to relink)\n",
+  "stderr": "",
+  "code": 1,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/doctor-dangling-symlink.json b/tests/golden/doctor-dangling-symlink.json
new file mode 100644
index 0000000..02052a8
--- /dev/null
+++ b/tests/golden/doctor-dangling-symlink.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories setup is unhealthy:\n  - git checkout missing at <TMP>/work/project/.claude/.memories-repo (run 'mcs sync' to re-clone)\n  - symlink exists but doesn't resolve to a git checkout (run 'mcs sync' to repair)\n",
+  "stderr": "",
+  "code": 1,
+  "git": "status-all: \nlog-all: \ntracked-all: \nstatus: \nlog: \nupstream: (none)\nunpushed: 0\ntracked: \nreview-shown: absent\nworktree: \nremote-log: \nremote-files: "
+}
diff --git a/tests/golden/doctor-healthy-setup-passes.json b/tests/golden/doctor-healthy-setup-passes.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/doctor-healthy-setup-passes.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/doctor-missing-checkout-and-symlink.json b/tests/golden/doctor-missing-checkout-and-symlink.json
new file mode 100644
index 0000000..5d17934
--- /dev/null
+++ b/tests/golden/doctor-missing-checkout-and-symlink.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories setup is unhealthy:\n  - git checkout missing at <TMP>/work/project/.claude/.memories-repo (run 'mcs sync' to re-clone)\n  - symlink missing at <TMP>/work/project/.claude/memories (run 'mcs sync' to relink)\n",
+  "stderr": "",
+  "code": 1,
+  "git": "status-all: \nlog-all: \ntracked-all: \nstatus: \nlog: \nupstream: (none)\nunpushed: 0\ntracked: \nreview-shown: absent\nworktree: \nremote-log: \nremote-files: "
+}
diff --git a/tests/golden/doctor-remote-no-checkout-skips.json b/tests/golden/doctor-remote-no-checkout-skips.json
new file mode 100644
index 0000000..daedf7f
--- /dev/null
+++ b/tests/golden/doctor-remote-no-checkout-skips.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 3,
+  "git": "status-all: \nlog-all: \ntracked-all: \nstatus: \nlog: \nupstream: (none)\nunpushed: 0\ntracked: \nreview-shown: absent\nworktree: \nremote-log: \nremote-files: "
+}
diff --git a/tests/golden/doctor-remote-reachable-remote-passes.json b/tests/golden/doctor-remote-reachable-remote-passes.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/doctor-remote-reachable-remote-passes.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/doctor-remote-unreachable-remote-warns.json b/tests/golden/doctor-remote-unreachable-remote-warns.json
new file mode 100644
index 0000000..b318f9a
--- /dev/null
+++ b/tests/golden/doctor-remote-unreachable-remote-warns.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Cannot reach the shared memories remote:\n  remote: /nonexistent/definitely-not-here.git\n  error:  fatal: '/nonexistent/definitely-not-here.git' does not appear to be a git repository\nfatal: Could not read from remote repository.\n\nPlease make sure you have the correct access rights\nand the repository exists.\n\nCommon causes:\n  - SSH key not loaded — try: ssh-add ~/.ssh/<your-key>\n  - Network offline or VPN disconnected\n  - Access revoked on the shared repo\n\nMemories still work locally; auto-push will retry on each Claude Stop once the remote is reachable.\n",
+  "stderr": "",
+  "code": 2,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/doctor-symlink-resolves-somewhere-that-is-not-a-checkout.json b/tests/golden/doctor-symlink-resolves-somewhere-that-is-not-a-checkout.json
new file mode 100644
index 0000000..f69cad7
--- /dev/null
+++ b/tests/golden/doctor-symlink-resolves-somewhere-that-is-not-a-checkout.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories setup is unhealthy:\n  - symlink exists but doesn't resolve to a git checkout (run 'mcs sync' to repair)\n",
+  "stderr": "",
+  "code": 1,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-a-badly-named-deleted-file-trips-the-guardrail.json b/tests/golden/edge-a-badly-named-deleted-file-trips-the-guardrail.json
new file mode 100644
index 0000000..1f2b2b3
--- /dev/null
+++ b/tests/golden/edge-a-badly-named-deleted-file-trips-the-guardrail.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: skipping auto-push — unconventional filename(s):\n  - memories/scratch.md\nRename to memories/learning_<topic>_<specific>.md or memories/decision_<domain>_<topic>.md so the guardrail accepts them.\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: D memories/scratch.md\nlog-all: add scratch | seed\ntracked-all: memories/learning_seed_topic.md | memories/scratch.md\nstatus: D memories/scratch.md\nlog: add scratch | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md | memories/scratch.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: add scratch | seed\nremote-files: memories/learning_seed_topic.md | memories/scratch.md"
+}
diff --git a/tests/golden/edge-a-commit-failure-is-reported-and-retried-next-stop.json b/tests/golden/edge-a-commit-failure-is-reported-and-retried-next-stop.json
new file mode 100644
index 0000000..5752f64
--- /dev/null
+++ b/tests/golden/edge-a-commit-failure-is-reported-and-retried-next-stop.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: commit failed; will retry on next Stop.\n  fatal: empty ident name (for <fixture@example.com>) not allowed\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: A  memories/learning_x_y.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md | memories/learning_x_y.md\nstatus: A  memories/learning_x_y.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md | memories/learning_x_y.md\nreview-shown: absent\nworktree: learning_seed_topic.md learning_x_y.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-a-dangling-memories-symlink-does-not-stop-the-push.json b/tests/golden/edge-a-dangling-memories-symlink-does-not-stop-the-push.json
new file mode 100644
index 0000000..5186b47
--- /dev/null
+++ b/tests/golden/edge-a-dangling-memories-symlink-does-not-stop-the-push.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | seed\ntracked-all: memories/learning_seed_topic.md | memories/learning_x_y.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md | memories/learning_x_y.md\nreview-shown: absent\nworktree: learning_seed_topic.md learning_x_y.md\nremote-log: auto: memories from <HOST> <DATE> | seed\nremote-files: memories/learning_seed_topic.md | memories/learning_x_y.md"
+}
diff --git a/tests/golden/edge-a-locked-index-aborts-the-turn-instead-of-reporting-nothing.json b/tests/golden/edge-a-locked-index-aborts-the-turn-instead-of-reporting-nothing.json
new file mode 100644
index 0000000..929ed6f
--- /dev/null
+++ b/tests/golden/edge-a-locked-index-aborts-the-turn-instead-of-reporting-nothing.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "fatal: Unable to create '<TMP>/work/project/.claude/.memories-repo/.git/index.lock': File exists.\n\nAnother git process seems to be running in this repository, or the lock file may be stale\nmemories_autopush: aborted (rc=128) at line 299: git -C \"$memories_dir\" add -- \"$f\"\n",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-a-typechange-to-a-symlink-is-unclassified-pending.json b/tests/golden/edge-a-typechange-to-a-symlink-is-unclassified-pending.json
new file mode 100644
index 0000000..8168de3
--- /dev/null
+++ b/tests/golden/edge-a-typechange-to-a-symlink-is-unclassified-pending.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 unclassified pending change(s) in memories/\n  Inspect: git -C .claude/.memories-repo status -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: T memories/learning_seed_topic.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: T memories/learning_seed_topic.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-an-empty-last-result-does-not-silence-the-nudge.json b/tests/golden/edge-an-empty-last-result-does-not-silence-the-nudge.json
new file mode 100644
index 0000000..2da0719
--- /dev/null
+++ b/tests/golden/edge-an-empty-last-result-does-not-silence-the-nudge.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /p/.claude/memories/learning_a_b.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-announce-drops-a-false-file-path-from-the-stream.json b/tests/golden/edge-announce-drops-a-false-file-path-from-the-stream.json
new file mode 100644
index 0000000..2da0719
--- /dev/null
+++ b/tests/golden/edge-announce-drops-a-false-file-path-from-the-stream.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /p/.claude/memories/learning_a_b.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-announce-ignores-a-null-file-path.json b/tests/golden/edge-announce-ignores-a-null-file-path.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/edge-announce-ignores-a-null-file-path.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-announce-is-silent-when-a-scalar-follows-a-valid-path.json b/tests/golden/edge-announce-is-silent-when-a-scalar-follows-a-valid-path.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/edge-announce-is-silent-when-a-scalar-follows-a-valid-path.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-announce-is-silent-when-stdin-is-a-bare-scalar.json b/tests/golden/edge-announce-is-silent-when-stdin-is-a-bare-scalar.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/edge-announce-is-silent-when-stdin-is-a-bare-scalar.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-announce-reads-every-value-in-a-concatenated-stream.json b/tests/golden/edge-announce-reads-every-value-in-a-concatenated-stream.json
new file mode 100644
index 0000000..c1fa673
--- /dev/null
+++ b/tests/golden/edge-announce-reads-every-value-in-a-concatenated-stream.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /p/.claude/memories/learning_a_b.md\\n/p/.claude/memories/learning_c_d.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-announce-renders-a-non-string-file-path-the-way-jq-does.json b/tests/golden/edge-announce-renders-a-non-string-file-path-the-way-jq-does.json
new file mode 100644
index 0000000..dd81084
--- /dev/null
+++ b/tests/golden/edge-announce-renders-a-non-string-file-path-the-way-jq-does.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at {\\n  \\\"x\\\": 1\\n}\\n/p/.claude/memories/learning_a_b.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-announce-still-reports-a-path-after-a-leading-scalar.json b/tests/golden/edge-announce-still-reports-a-path-after-a-leading-scalar.json
new file mode 100644
index 0000000..2da0719
--- /dev/null
+++ b/tests/golden/edge-announce-still-reports-a-path-after-a-leading-scalar.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /p/.claude/memories/learning_a_b.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-announce-strips-a-trailing-newline-the-way-did.json b/tests/golden/edge-announce-strips-a-trailing-newline-the-way-did.json
new file mode 100644
index 0000000..2da0719
--- /dev/null
+++ b/tests/golden/edge-announce-strips-a-trailing-newline-the-way-did.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /p/.claude/memories/learning_a_b.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-announce-when-only-the-second-value-carries-a-path.json b/tests/golden/edge-announce-when-only-the-second-value-carries-a-path.json
new file mode 100644
index 0000000..9a1b741
--- /dev/null
+++ b/tests/golden/edge-announce-when-only-the-second-value-carries-a-path.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PostToolUse\",\n    \"additionalContext\": \"Memory file saved at /p/.claude/memories/learning_c_d.md (MEMORIES_AUTOPUSH_MODE=review). This memory will not auto-push. Mention the pending memory to the user before ending your turn so they can decide whether to approve or discard. If they approve, run /approve-memories.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-changes-already-staged-in-the-index-still-commit.json b/tests/golden/edge-changes-already-staged-in-the-index-still-commit.json
new file mode 100644
index 0000000..5186b47
--- /dev/null
+++ b/tests/golden/edge-changes-already-staged-in-the-index-still-commit.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | seed\ntracked-all: memories/learning_seed_topic.md | memories/learning_x_y.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md | memories/learning_x_y.md\nreview-shown: absent\nworktree: learning_seed_topic.md learning_x_y.md\nremote-log: auto: memories from <HOST> <DATE> | seed\nremote-files: memories/learning_seed_topic.md | memories/learning_x_y.md"
+}
diff --git a/tests/golden/edge-review-on-a-detached-head-with-an-unpushed-commit.json b/tests/golden/edge-review-on-a-detached-head-with-an-unpushed-commit.json
new file mode 100644
index 0000000..679b062
--- /dev/null
+++ b/tests/golden/edge-review-on-a-detached-head-with-an-unpushed-commit.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: local | seed\ntracked-all: memories/learning_seed_topic.md | memories/learning_x_y.md\nstatus: \nlog: local | seed\nupstream: (none)\nunpushed: 0\ntracked: memories/learning_seed_topic.md | memories/learning_x_y.md\nreview-shown: absent\nworktree: learning_seed_topic.md learning_x_y.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-review-reports-a-staged-rename-as-unclassified-pending.json b/tests/golden/edge-review-reports-a-staged-rename-as-unclassified-pending.json
new file mode 100644
index 0000000..d69a65d
--- /dev/null
+++ b/tests/golden/edge-review-reports-a-staged-rename-as-unclassified-pending.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 unclassified pending change(s) in memories/\n  Inspect: git -C .claude/.memories-repo status -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: R  memories/learning_seed_topic.md -> memories/learning_seed_renamed.md\nlog-all: seed\ntracked-all: memories/learning_seed_renamed.md\nstatus: R  memories/learning_seed_topic.md -> memories/learning_seed_renamed.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_renamed.md\nreview-shown: absent\nworktree: learning_seed_renamed.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/edge-sessionstart-survives-a-failed-fast-forward.json b/tests/golden/edge-sessionstart-survives-a-failed-fast-forward.json
new file mode 100644
index 0000000..f5f3271
--- /dev/null
+++ b/tests/golden/edge-sessionstart-survives-a-failed-fast-forward.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 unpushed commit(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: ours | seed\ntracked-all: memories/learning_ours_b.md | memories/learning_seed_topic.md\nstatus: \nlog: ours | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_ours_b.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_ours_b.md learning_seed_topic.md\nremote-log: teammate memory | seed\nremote-files: memories/learning_seed_topic.md | memories/learning_theirs_a.md"
+}
diff --git a/tests/golden/incoming-a-fast-forward-alongside-our-own-untracked-memory.json b/tests/golden/incoming-a-fast-forward-alongside-our-own-untracked-memory.json
new file mode 100644
index 0000000..431bf0a
--- /dev/null
+++ b/tests/golden/incoming-a-fast-forward-alongside-our-own-untracked-memory.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 uncommitted file(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_ours_pending.md\nlog-all: teammate memory | seed\ntracked-all: memories/learning_seed_topic.md | memories/learning_theirs_new.md\nstatus: ?? memories/learning_ours_pending.md\nlog: teammate memory | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md | memories/learning_theirs_new.md\nreview-shown: absent\nworktree: learning_ours_pending.md learning_seed_topic.md learning_theirs_new.md\nremote-log: teammate memory | seed\nremote-files: memories/learning_seed_topic.md | memories/learning_theirs_new.md"
+}
diff --git a/tests/golden/incoming-sessionstart-does-not-fast-forward-past-a-conflicting-local-commit.json b/tests/golden/incoming-sessionstart-does-not-fast-forward-past-a-conflicting-local-commit.json
new file mode 100644
index 0000000..e8a6f1a
--- /dev/null
+++ b/tests/golden/incoming-sessionstart-does-not-fast-forward-past-a-conflicting-local-commit.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 unpushed commit(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: our local commit | seed\ntracked-all: memories/learning_ours_own.md | memories/learning_seed_topic.md\nstatus: \nlog: our local commit | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_ours_own.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_ours_own.md learning_seed_topic.md\nremote-log: teammate memory | seed\nremote-files: memories/learning_seed_topic.md | memories/learning_theirs_new.md"
+}
diff --git a/tests/golden/incoming-sessionstart-fast-forwards-a-teammate-s-memory.json b/tests/golden/incoming-sessionstart-fast-forwards-a-teammate-s-memory.json
new file mode 100644
index 0000000..1bc6848
--- /dev/null
+++ b/tests/golden/incoming-sessionstart-fast-forwards-a-teammate-s-memory.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: teammate memory | seed\ntracked-all: memories/learning_seed_topic.md | memories/learning_theirs_new.md\nstatus: \nlog: teammate memory | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md | memories/learning_theirs_new.md\nreview-shown: absent\nworktree: learning_seed_topic.md learning_theirs_new.md\nremote-log: teammate memory | seed\nremote-files: memories/learning_seed_topic.md | memories/learning_theirs_new.md"
+}
diff --git a/tests/golden/incoming-the-stop-hook-rebases-onto-a-teammate-s-commit.json b/tests/golden/incoming-the-stop-hook-rebases-onto-a-teammate-s-commit.json
new file mode 100644
index 0000000..be43e50
--- /dev/null
+++ b/tests/golden/incoming-the-stop-hook-rebases-onto-a-teammate-s-commit.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | teammate memory | seed\ntracked-all: memories/learning_ours_own.md | memories/learning_seed_topic.md | memories/learning_theirs_new.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | teammate memory | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_ours_own.md | memories/learning_seed_topic.md | memories/learning_theirs_new.md\nreview-shown: absent\nworktree: learning_ours_own.md learning_seed_topic.md learning_theirs_new.md\nremote-log: auto: memories from <HOST> <DATE> | teammate memory | seed\nremote-files: memories/learning_ours_own.md | memories/learning_seed_topic.md | memories/learning_theirs_new.md"
+}
diff --git a/tests/golden/pathspec-a-dirty-root-file-does-not-trip-the-filename-guardrail.json b/tests/golden/pathspec-a-dirty-root-file-does-not-trip-the-filename-guardrail.json
new file mode 100644
index 0000000..c321b1d
--- /dev/null
+++ b/tests/golden/pathspec-a-dirty-root-file-does-not-trip-the-filename-guardrail.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: M README.md\nlog-all: add a root README | seed\ntracked-all: README.md | memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: add a root README | seed\nremote-files: README.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pathspec-auto-mode-leaves-a-dirty-root-file-uncommitted.json b/tests/golden/pathspec-auto-mode-leaves-a-dirty-root-file-uncommitted.json
new file mode 100644
index 0000000..718d33d
--- /dev/null
+++ b/tests/golden/pathspec-auto-mode-leaves-a-dirty-root-file-uncommitted.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: M README.md\nlog-all: auto: memories from <HOST> <DATE> | add a root README | seed\ntracked-all: README.md | memories/learning_new_thing.md | memories/learning_seed_topic.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_new_thing.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: auto: memories from <HOST> <DATE> | add a root README | seed\nremote-files: README.md | memories/learning_new_thing.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pathspec-full-mode-leaves-a-dirty-root-file-uncommitted.json b/tests/golden/pathspec-full-mode-leaves-a-dirty-root-file-uncommitted.json
new file mode 100644
index 0000000..718d33d
--- /dev/null
+++ b/tests/golden/pathspec-full-mode-leaves-a-dirty-root-file-uncommitted.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: M README.md\nlog-all: auto: memories from <HOST> <DATE> | add a root README | seed\ntracked-all: README.md | memories/learning_new_thing.md | memories/learning_seed_topic.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_new_thing.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: auto: memories from <HOST> <DATE> | add a root README | seed\nremote-files: README.md | memories/learning_new_thing.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pathspec-review-mode-does-not-report-a-dirty-root-file.json b/tests/golden/pathspec-review-mode-does-not-report-a-dirty-root-file.json
new file mode 100644
index 0000000..3b3d276
--- /dev/null
+++ b/tests/golden/pathspec-review-mode-does-not-report-a-dirty-root-file.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"A lesson.\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md | M README.md\nlog-all: add a root README | seed\ntracked-all: README.md | memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: add a root README | seed\nremote-files: README.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pathspec-sessionstart-does-not-count-a-dirty-root-file-as-pending.json b/tests/golden/pathspec-sessionstart-does-not-count-a-dirty-root-file-as-pending.json
new file mode 100644
index 0000000..c321b1d
--- /dev/null
+++ b/tests/golden/pathspec-sessionstart-does-not-count-a-dirty-root-file-as-pending.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: M README.md\nlog-all: add a root README | seed\ntracked-all: README.md | memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: add a root README | seed\nremote-files: README.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/preflight-a-missing-branch-touches-nothing.json b/tests/golden/preflight-a-missing-branch-touches-nothing.json
new file mode 100644
index 0000000..c56fbbb
--- /dev/null
+++ b/tests/golden/preflight-a-missing-branch-touches-nothing.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "Cannot set up shared memories — remote is unreachable or branch missing.\n  remote: <TMP>/work/remote.git\n  branch: nope\n  error:  \n\nCommon causes:\n  - SSH key not loaded — try: ssh-add ~/.ssh/<your-key>\n  - Network offline or VPN disconnected\n  - Access revoked on the shared repo\n  - Branch 'nope' does not exist on the remote\n\nYour existing memories at <TMP>/work/project/.claude/memories have not been touched.\n",
+  "code": 1,
+  "git": ""
+}
diff --git a/tests/golden/preflight-an-unreachable-remote-touches-nothing.json b/tests/golden/preflight-an-unreachable-remote-touches-nothing.json
new file mode 100644
index 0000000..c4fa8ef
--- /dev/null
+++ b/tests/golden/preflight-an-unreachable-remote-touches-nothing.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "Cannot set up shared memories — remote is unreachable or branch missing.\n  remote: /nonexistent/definitely-not-here.git\n  branch: main\n  error:  fatal: '/nonexistent/definitely-not-here.git' does not appear to be a git repository\nfatal: Could not read from remote repository.\n\nPlease make sure you have the correct access rights\nand the repository exists.\n\nCommon causes:\n  - SSH key not loaded — try: ssh-add ~/.ssh/<your-key>\n  - Network offline or VPN disconnected\n  - Access revoked on the shared repo\n  - Branch 'main' does not exist on the remote\n\nYour existing memories at <TMP>/work/project/.claude/memories have not been touched.\n",
+  "code": 1,
+  "git": "memories\nlearning_mine_own.md"
+}
diff --git a/tests/golden/pull-auto-mode-leaves-the-dedupe-state-file-alone.json b/tests/golden/pull-auto-mode-leaves-the-dedupe-state-file-alone.json
new file mode 100644
index 0000000..9f3aeb8
--- /dev/null
+++ b/tests/golden/pull-auto-mode-leaves-the-dedupe-state-file-alone.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-clean-tree-auto.json b/tests/golden/pull-clean-tree-auto.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/pull-clean-tree-auto.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-clean-tree-review.json b/tests/golden/pull-clean-tree-review.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/pull-clean-tree-review.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-concatenated-json-stream-is-accepted.json b/tests/golden/pull-concatenated-json-stream-is-accepted.json
new file mode 100644
index 0000000..431554d
--- /dev/null
+++ b/tests/golden/pull-concatenated-json-stream-is-accepted.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 uncommitted file(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_pending_one.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_pending_one.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_pending_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-empty-mode-falls-through-to-auto.json b/tests/golden/pull-empty-mode-falls-through-to-auto.json
new file mode 100644
index 0000000..431554d
--- /dev/null
+++ b/tests/golden/pull-empty-mode-falls-through-to-auto.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 uncommitted file(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_pending_one.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_pending_one.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_pending_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-empty-stdin-still-does-the-work.json b/tests/golden/pull-empty-stdin-still-does-the-work.json
new file mode 100644
index 0000000..431554d
--- /dev/null
+++ b/tests/golden/pull-empty-stdin-still-does-the-work.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 uncommitted file(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_pending_one.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_pending_one.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_pending_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-malformed-stdin.json b/tests/golden/pull-malformed-stdin.json
new file mode 100644
index 0000000..0823d92
--- /dev/null
+++ b/tests/golden/pull-malformed-stdin.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "memories_pull: stdin is not valid JSON; skipping\n",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-missing-checkout.json b/tests/golden/pull-missing-checkout.json
new file mode 100644
index 0000000..7abad6e
--- /dev/null
+++ b/tests/golden/pull-missing-checkout.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "memories_pull: <TMP>/work/project/.claude/.memories-repo is not a git worktree; skipping (project_root=<TMP>/work/project)\n",
+  "code": 0,
+  "git": "status-all: \nlog-all: \ntracked-all: \nstatus: \nlog: \nupstream: (none)\nunpushed: 0\ntracked: \nreview-shown: absent\nworktree: \nremote-log: \nremote-files: "
+}
diff --git a/tests/golden/pull-no-upstream-configured.json b/tests/golden/pull-no-upstream-configured.json
new file mode 100644
index 0000000..761e21b
--- /dev/null
+++ b/tests/golden/pull-no-upstream-configured.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 uncommitted file(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_pending_one.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_pending_one.md\nlog: seed\nupstream: (none)\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_pending_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-review-mode-clears-the-dedupe-state-file.json b/tests/golden/pull-review-mode-clears-the-dedupe-state-file.json
new file mode 100644
index 0000000..6e86273
--- /dev/null
+++ b/tests/golden/pull-review-mode-clears-the-dedupe-state-file.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-two-untracked-memories-pluralise-the-same-way.json b/tests/golden/pull-two-untracked-memories-pluralise-the-same-way.json
new file mode 100644
index 0000000..e921fe8
--- /dev/null
+++ b/tests/golden/pull-two-untracked-memories-pluralise-the-same-way.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 2 uncommitted file(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_pending_one.md | ?? memories/learning_pending_two.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_pending_one.md | ?? memories/learning_pending_two.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_pending_one.md learning_pending_two.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-uncommitted-and-unpushed-together.json b/tests/golden/pull-uncommitted-and-unpushed-together.json
new file mode 100644
index 0000000..5f2dfef
--- /dev/null
+++ b/tests/golden/pull-uncommitted-and-unpushed-together.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 uncommitted file(s), 1 unpushed commit(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_dirty_y.md\nlog-all: local only | seed\ntracked-all: memories/learning_committed_x.md | memories/learning_seed_topic.md\nstatus: ?? memories/learning_dirty_y.md\nlog: local only | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_committed_x.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_committed_x.md learning_dirty_y.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-unknown-mode-warning-joins-the-pending-message.json b/tests/golden/pull-unknown-mode-warning-joins-the-pending-message.json
new file mode 100644
index 0000000..0977a7b
--- /dev/null
+++ b/tests/golden/pull-unknown-mode-warning-joins-the-pending-message.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories: unknown MEMORIES_AUTOPUSH_MODE='banana' — falling back to auto. Fix the value in .claude/settings.local.json (valid: auto, full, review) and restart the session.\\n\\nShared memories have lingering state: 1 uncommitted file(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_pending_one.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_pending_one.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_pending_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-unknown-mode-warns-clean-tree.json b/tests/golden/pull-unknown-mode-warns-clean-tree.json
new file mode 100644
index 0000000..60c5f21
--- /dev/null
+++ b/tests/golden/pull-unknown-mode-warns-clean-tree.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories: unknown MEMORIES_AUTOPUSH_MODE='banana' — falling back to auto. Fix the value in .claude/settings.local.json (valid: auto, full, review) and restart the session.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-unpushed-commit-only.json b/tests/golden/pull-unpushed-commit-only.json
new file mode 100644
index 0000000..d00a048
--- /dev/null
+++ b/tests/golden/pull-unpushed-commit-only.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 unpushed commit(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: local only | seed\ntracked-all: memories/learning_committed_x.md | memories/learning_seed_topic.md\nstatus: \nlog: local only | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_committed_x.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_committed_x.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-untracked-memory-auto-reports-lingering-state.json b/tests/golden/pull-untracked-memory-auto-reports-lingering-state.json
new file mode 100644
index 0000000..431554d
--- /dev/null
+++ b/tests/golden/pull-untracked-memory-auto-reports-lingering-state.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories have lingering state: 1 uncommitted file(s). The previous Stop hook's auto-push didn't complete — check SSH auth (ssh-add), network, or file naming (must match memories/{learning,decision}_<name>.md). The next Stop will retry automatically.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_pending_one.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_pending_one.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_pending_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/pull-untracked-memory-review-reports-awaiting-review.json b/tests/golden/pull-untracked-memory-review-reports-awaiting-review.json
new file mode 100644
index 0000000..2a37fa5
--- /dev/null
+++ b/tests/golden/pull-untracked-memory-review-reports-awaiting-review.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"SessionStart\",\n    \"additionalContext\": \"Shared memories: 1 uncommitted file(s) awaiting review (MEMORIES_AUTOPUSH_MODE=review). End a turn to see the per-file report with approve/discard commands.\"\n  }\n}\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? memories/learning_pending_one.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_pending_one.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_pending_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/push-a-non-integer-attempt-budget-falls-back-to-the-default.json b/tests/golden/push-a-non-integer-attempt-budget-falls-back-to-the-default.json
new file mode 100644
index 0000000..731b2e0
--- /dev/null
+++ b/tests/golden/push-a-non-integer-attempt-budget-falls-back-to-the-default.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | from the other clone | seed\ntracked-all: memories/learning_ours_one.md | memories/learning_seed_topic.md | memories/learning_theirs_one.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | from the other clone | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_ours_one.md | memories/learning_seed_topic.md | memories/learning_theirs_one.md\nreview-shown: absent\nworktree: learning_ours_one.md learning_seed_topic.md learning_theirs_one.md\nremote-log: auto: memories from <HOST> <DATE> | from the other clone | seed\nremote-files: memories/learning_ours_one.md | memories/learning_seed_topic.md | memories/learning_theirs_one.md"
+}
diff --git a/tests/golden/push-a-rebase-conflict-pauses-and-aborts.json b/tests/golden/push-a-rebase-conflict-pauses-and-aborts.json
new file mode 100644
index 0000000..5a9d184
--- /dev/null
+++ b/tests/golden/push-a-rebase-conflict-pauses-and-aborts.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: auto-push paused — rebase conflict. Resolve manually in .claude/.memories-repo/memories.\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: our conflicting edit | seed\ntracked-all: memories/learning_seed_topic.md\nstatus: \nlog: our conflicting edit | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_seed_topic.md\nremote-log: from the other clone | seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/push-a-rejected-push-rebases-and-retries-into-success.json b/tests/golden/push-a-rejected-push-rebases-and-retries-into-success.json
new file mode 100644
index 0000000..731b2e0
--- /dev/null
+++ b/tests/golden/push-a-rejected-push-rebases-and-retries-into-success.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | from the other clone | seed\ntracked-all: memories/learning_ours_one.md | memories/learning_seed_topic.md | memories/learning_theirs_one.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | from the other clone | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_ours_one.md | memories/learning_seed_topic.md | memories/learning_theirs_one.md\nreview-shown: absent\nworktree: learning_ours_one.md learning_seed_topic.md learning_theirs_one.md\nremote-log: auto: memories from <HOST> <DATE> | from the other clone | seed\nremote-files: memories/learning_ours_one.md | memories/learning_seed_topic.md | memories/learning_theirs_one.md"
+}
diff --git a/tests/golden/push-a-zero-attempt-budget-still-tries-once.json b/tests/golden/push-a-zero-attempt-budget-still-tries-once.json
new file mode 100644
index 0000000..731b2e0
--- /dev/null
+++ b/tests/golden/push-a-zero-attempt-budget-still-tries-once.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: auto: memories from <HOST> <DATE> | from the other clone | seed\ntracked-all: memories/learning_ours_one.md | memories/learning_seed_topic.md | memories/learning_theirs_one.md\nstatus: \nlog: auto: memories from <HOST> <DATE> | from the other clone | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_ours_one.md | memories/learning_seed_topic.md | memories/learning_theirs_one.md\nreview-shown: absent\nworktree: learning_ours_one.md learning_seed_topic.md learning_theirs_one.md\nremote-log: auto: memories from <HOST> <DATE> | from the other clone | seed\nremote-files: memories/learning_ours_one.md | memories/learning_seed_topic.md | memories/learning_theirs_one.md"
+}
diff --git a/tests/golden/push-an-unreachable-remote-reports-auth-or-network.json b/tests/golden/push-an-unreachable-remote-reports-auth-or-network.json
new file mode 100644
index 0000000..f59c625
--- /dev/null
+++ b/tests/golden/push-an-unreachable-remote-reports-auth-or-network.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories: pull --rebase failed (likely auth or network). Will retry on next Stop.\n  fatal: '/nonexistent/definitely-not-here.git' does not appear to be a git repository\nfatal: Could not read from remote repository.\n\nPlease make sure you have the correct access rights\nand the repository exists.\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: \nlog-all: local only | seed\ntracked-all: memories/learning_ours_one.md | memories/learning_seed_topic.md\nstatus: \nlog: local only | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_ours_one.md | memories/learning_seed_topic.md\nreview-shown: absent\nworktree: learning_ours_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-a-bare-carriage-return-is-preserved-as-the-bash-preserves-it.json b/tests/golden/review-a-bare-carriage-return-is-preserved-as-the-bash-preserves-it.json
new file mode 100644
index 0000000..c470036
--- /dev/null
+++ b/tests/golden/review-a-bare-carriage-return-is-preserved-as-the-bash-preserves-it.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"before\rafter\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-a-deletion-renders-its-relative-timestamp.json b/tests/golden/review-a-deletion-renders-its-relative-timestamp.json
new file mode 100644
index 0000000..2f8bdc7
--- /dev/null
+++ b/tests/golden/review-a-deletion-renders-its-relative-timestamp.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n- DEL  memories/learning_seed_topic.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_seed_topic.md\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | D memories/learning_seed_topic.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: D memories/learning_seed_topic.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: \nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-a-modification-renders-numstat.json b/tests/golden/review-a-modification-renders-numstat.json
new file mode 100644
index 0000000..ad35ae0
--- /dev/null
+++ b/tests/golden/review-a-modification-renders-numstat.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n~ MOD  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_seed_topic.md>  (+3 -1)\n       Diff: git -C .claude/.memories-repo diff -- memories/learning_seed_topic.md\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | M memories/learning_seed_topic.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: M memories/learning_seed_topic.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-a-new-file-renders-with-its-preview.json b/tests/golden/review-a-new-file-renders-with-its-preview.json
new file mode 100644
index 0000000..f004b5d
--- /dev/null
+++ b/tests/golden/review-a-new-file-renders-with-its-preview.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"First real line of the memory.\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-a-preview-longer-than-80-chars-is-truncated.json b/tests/golden/review-a-preview-longer-than-80-chars-is-truncated.json
new file mode 100644
index 0000000..34ce403
--- /dev/null
+++ b/tests/golden/review-a-preview-longer-than-80-chars-is-truncated.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-a-stale-stored-hash-reprints.json b/tests/golden/review-a-stale-stored-hash-reprints.json
new file mode 100644
index 0000000..3de8879
--- /dev/null
+++ b/tests/golden/review-a-stale-stored-hash-reprints.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"A lesson.\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-a-tab-in-the-preview-survives.json b/tests/golden/review-a-tab-in-the-preview-survives.json
new file mode 100644
index 0000000..b34836d
--- /dev/null
+++ b/tests/golden/review-a-tab-in-the-preview-survives.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"before\tafter\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-adding-a-file-after-a-report-reprints.json b/tests/golden/review-adding-a-file-after-a-report-reprints.json
new file mode 100644
index 0000000..ccabaf5
--- /dev/null
+++ b/tests/golden/review-adding-a-file-after-a-report-reprints.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 2 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"A lesson.\"\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_second_one.md>\n       \"Another lesson.\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md | ?? memories/learning_second_one.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md | ?? memories/learning_second_one.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_second_one.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-an-empty-file-emits-no-preview-line.json b/tests/golden/review-an-empty-file-emits-no-preview-line.json
new file mode 100644
index 0000000..0a08b67
--- /dev/null
+++ b/tests/golden/review-an-empty-file-emits-no-preview-line.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-ansi-escapes-in-a-memory-never-reach-the-terminal.json b/tests/golden/review-ansi-escapes-in-a-memory-never-reach-the-terminal.json
new file mode 100644
index 0000000..be4a37d
--- /dev/null
+++ b/tests/golden/review-ansi-escapes-in-a-memory-never-reach-the-terminal.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"safe[31mRED text\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-new-modified-and-deleted-together.json b/tests/golden/review-new-modified-and-deleted-together.json
new file mode 100644
index 0000000..8b479a8
--- /dev/null
+++ b/tests/golden/review-new-modified-and-deleted-together.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 3 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_brand_new.md>\n       \"Brand new.\"\n~ MOD  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_seed_topic.md>  (+1 -1)\n       Diff: git -C .claude/.memories-repo diff -- memories/learning_seed_topic.md\n- DEL  memories/learning_extra_one.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_extra_one.md\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all:  M memories/learning_seed_topic.md | ?? .review-shown | ?? memories/learning_brand_new.md | D memories/learning_extra_one.md\nlog-all: add extra | seed\ntracked-all: memories/learning_extra_one.md | memories/learning_seed_topic.md\nstatus:  M memories/learning_seed_topic.md | ?? memories/learning_brand_new.md | D memories/learning_extra_one.md\nlog: add extra | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_extra_one.md | memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_brand_new.md learning_seed_topic.md\nremote-log: add extra | seed\nremote-files: memories/learning_extra_one.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-pending-files-plus-an-unpushed-commit.json b/tests/golden/review-pending-files-plus-an-unpushed-commit.json
new file mode 100644
index 0000000..50729b6
--- /dev/null
+++ b/tests/golden/review-pending-files-plus-an-unpushed-commit.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/ and 1 unpushed commit(s)\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_brand_new.md>\n       \"Brand new.\"\n\n  Note: 1 local commit(s) not yet on the remote.\n        Push: git -C .claude/.memories-repo pull --rebase --autostash && git -C .claude/.memories-repo push\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_brand_new.md\nlog-all: local only | seed\ntracked-all: memories/learning_committed_x.md | memories/learning_seed_topic.md\nstatus: ?? memories/learning_brand_new.md\nlog: local only | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_committed_x.md | memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_brand_new.md learning_committed_x.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-preview-skips-leading-blank-and-whitespace-only-lines.json b/tests/golden/review-preview-skips-leading-blank-and-whitespace-only-lines.json
new file mode 100644
index 0000000..20cf0ea
--- /dev/null
+++ b/tests/golden/review-preview-skips-leading-blank-and-whitespace-only-lines.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 pending file(s) in memories/\n+ NEW  <file://<TMP>/work/project/.claude/.memories-repo/memories/learning_new_thing.md>\n       \"Actual content here.\"\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-the-same-pending-set-is-reported-once.json b/tests/golden/review-the-same-pending-set-is-reported-once.json
new file mode 100644
index 0000000..0014f7b
--- /dev/null
+++ b/tests/golden/review-the-same-pending-set-is-reported-once.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown | ?? memories/learning_new_thing.md\nlog-all: seed\ntracked-all: memories/learning_seed_topic.md\nstatus: ?? memories/learning_new_thing.md\nlog: seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_new_thing.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-twenty-one-deletions-straddle-the-timestamp-cap.json b/tests/golden/review-twenty-one-deletions-straddle-the-timestamp-cap.json
new file mode 100644
index 0000000..233de1a
--- /dev/null
+++ b/tests/golden/review-twenty-one-deletions-straddle-the-timestamp-cap.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 21 pending file(s) in memories/\n- DEL  memories/learning_bulk_00.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_00.md\n- DEL  memories/learning_bulk_01.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_01.md\n- DEL  memories/learning_bulk_02.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_02.md\n- DEL  memories/learning_bulk_03.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_03.md\n- DEL  memories/learning_bulk_04.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_04.md\n- DEL  memories/learning_bulk_05.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_05.md\n- DEL  memories/learning_bulk_06.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_06.md\n- DEL  memories/learning_bulk_07.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_07.md\n- DEL  memories/learning_bulk_08.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_08.md\n- DEL  memories/learning_bulk_09.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_09.md\n- DEL  memories/learning_bulk_10.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_10.md\n- DEL  memories/learning_bulk_11.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_11.md\n- DEL  memories/learning_bulk_12.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_12.md\n- DEL  memories/learning_bulk_13.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_13.md\n- DEL  memories/learning_bulk_14.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_14.md\n- DEL  memories/learning_bulk_15.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_15.md\n- DEL  memories/learning_bulk_16.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_16.md\n- DEL  memories/learning_bulk_17.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_17.md\n- DEL  memories/learning_bulk_18.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_18.md\n- DEL  memories/learning_bulk_19.md  (last modified <REL>)\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_19.md\n- DEL  memories/learning_bulk_20.md\n       Recover: git -C .claude/.memories-repo checkout HEAD -- memories/learning_bulk_20.md\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all:  D memories/learning_bulk_01.md |  D memories/learning_bulk_02.md |  D memories/learning_bulk_03.md |  D memories/learning_bulk_04.md |  D memories/learning_bulk_05.md |  D memories/learning_bulk_06.md |  D memories/learning_bulk_07.md |  D memories/learning_bulk_08.md |  D memories/learning_bulk_09.md |  D memories/learning_bulk_10.md |  D memories/learning_bulk_11.md |  D memories/learning_bulk_12.md |  D memories/learning_bulk_13.md |  D memories/learning_bulk_14.md |  D memories/learning_bulk_15.md |  D memories/learning_bulk_16.md |  D memories/learning_bulk_17.md |  D memories/learning_bulk_18.md |  D memories/learning_bulk_19.md |  D memories/learning_bulk_20.md | ?? .review-shown | D memories/learning_bulk_00.md\nlog-all: bulk | seed\ntracked-all: memories/learning_bulk_00.md | memories/learning_bulk_01.md | memories/learning_bulk_02.md | memories/learning_bulk_03.md | memories/learning_bulk_04.md | memories/learning_bulk_05.md | memories/learning_bulk_06.md | memories/learning_bulk_07.md | memories/learning_bulk_08.md | memories/learning_bulk_09.md | memories/learning_bulk_10.md | memories/learning_bulk_11.md | memories/learning_bulk_12.md | memories/learning_bulk_13.md | memories/learning_bulk_14.md | memories/learning_bulk_15.md | memories/learning_bulk_16.md | memories/learning_bulk_17.md | memories/learning_bulk_18.md | memories/learning_bulk_19.md | memories/learning_bulk_20.md | memories/learning_seed_topic.md\nstatus:  D memories/learning_bulk_01.md |  D memories/learning_bulk_02.md |  D memories/learning_bulk_03.md |  D memories/learning_bulk_04.md |  D memories/learning_bulk_05.md |  D memories/learning_bulk_06.md |  D memories/learning_bulk_07.md |  D memories/learning_bulk_08.md |  D memories/learning_bulk_09.md |  D memories/learning_bulk_10.md |  D memories/learning_bulk_11.md |  D memories/learning_bulk_12.md |  D memories/learning_bulk_13.md |  D memories/learning_bulk_14.md |  D memories/learning_bulk_15.md |  D memories/learning_bulk_16.md |  D memories/learning_bulk_17.md |  D memories/learning_bulk_18.md |  D memories/learning_bulk_19.md |  D memories/learning_bulk_20.md | D memories/learning_bulk_00.md\nlog: bulk | seed\nupstream: origin/main\nunpushed: 0\ntracked: memories/learning_bulk_00.md | memories/learning_bulk_01.md | memories/learning_bulk_02.md | memories/learning_bulk_03.md | memories/learning_bulk_04.md | memories/learning_bulk_05.md | memories/learning_bulk_06.md | memories/learning_bulk_07.md | memories/learning_bulk_08.md | memories/learning_bulk_09.md | memories/learning_bulk_10.md | memories/learning_bulk_11.md | memories/learning_bulk_12.md | memories/learning_bulk_13.md | memories/learning_bulk_14.md | memories/learning_bulk_15.md | memories/learning_bulk_16.md | memories/learning_bulk_17.md | memories/learning_bulk_18.md | memories/learning_bulk_19.md | memories/learning_bulk_20.md | memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_seed_topic.md\nremote-log: bulk | seed\nremote-files: memories/learning_bulk_00.md | memories/learning_bulk_01.md | memories/learning_bulk_02.md | memories/learning_bulk_03.md | memories/learning_bulk_04.md | memories/learning_bulk_05.md | memories/learning_bulk_06.md | memories/learning_bulk_07.md | memories/learning_bulk_08.md | memories/learning_bulk_09.md | memories/learning_bulk_10.md | memories/learning_bulk_11.md | memories/learning_bulk_12.md | memories/learning_bulk_13.md | memories/learning_bulk_14.md | memories/learning_bulk_15.md | memories/learning_bulk_16.md | memories/learning_bulk_17.md | memories/learning_bulk_18.md | memories/learning_bulk_19.md | memories/learning_bulk_20.md | memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/review-unpushed-commit-with-no-dirty-files.json b/tests/golden/review-unpushed-commit-with-no-dirty-files.json
new file mode 100644
index 0000000..e70c72d
--- /dev/null
+++ b/tests/golden/review-unpushed-commit-with-no-dirty-files.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Shared memories [review mode]: 1 unpushed commit(s)\n\n  Note: 1 local commit(s) not yet on the remote.\n        Push: git -C .claude/.memories-repo pull --rebase --autostash && git -C .claude/.memories-repo push\n\nApprove all:           /approve-memories  [optional commit reason]\nDiscard local changes: git -C .claude/.memories-repo checkout -- memories/ \\\n                       && git -C .claude/.memories-repo clean -f -- memories/\n",
+  "stderr": "",
+  "code": 0,
+  "git": "status-all: ?? .review-shown\nlog-all: local only | seed\ntracked-all: memories/learning_committed_x.md | memories/learning_seed_topic.md\nstatus: \nlog: local only | seed\nupstream: origin/main\nunpushed: 1\ntracked: memories/learning_committed_x.md | memories/learning_seed_topic.md\nreview-shown: present\nworktree: learning_committed_x.md learning_seed_topic.md\nremote-log: seed\nremote-files: memories/learning_seed_topic.md"
+}
diff --git a/tests/golden/unchecked-a-dangling-symlink-is-skipped-not-fatal.json b/tests/golden/unchecked-a-dangling-symlink-is-skipped-not-fatal.json
new file mode 100644
index 0000000..82d855e
--- /dev/null
+++ b/tests/golden/unchecked-a-dangling-symlink-is-skipped-not-fatal.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 2 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 1 local memory file(s); 0 conflict(s) (shared version kept); 0 previously-deleted file(s) held back.\n  Kept at <TMP>/work/project/.claude/.memories-migration-<TS> for review.\nPushed migrated memories to the shared branch.\nDone. 2 memory file(s) available at <TMP>/work/project/.claude/memories.\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\n",
+  "code": 0,
+  "git": ".memories-migration-<TS> .memories-repo memories\nlearning_mine_own.md learning_shared_seed.md"
+}
diff --git a/tests/golden/unchecked-a-failed-migration-commit-is-not-reported-as-a-push.json b/tests/golden/unchecked-a-failed-migration-commit-is-not-reported-as-a-push.json
new file mode 100644
index 0000000..74a14b9
--- /dev/null
+++ b/tests/golden/unchecked-a-failed-migration-commit-is-not-reported-as-a-push.json
@@ -0,0 +1,6 @@
+{
+  "stdout": "Found pre-existing <TMP>/work/project/.claude/memories with 1 entr(y/ies) — staging for migration...\n  → backing up to <TMP>/work/project/.claude/.memories-migration-<TS>\nCloning shared memories (branch 'main', sparse) into <TMP>/work/project/.claude/.memories-repo...\nMigration: imported 1 local memory file(s); 0 conflict(s) (shared version kept).\n",
+  "stderr": "Cloning into '<TMP>/work/project/.claude/.memories-repo'...\nwarning: --filter is ignored in local clones; use file:// instead.\ndone.\nfatal: empty ident name (for <>) not allowed\n",
+  "code": 128,
+  "git": ".memories-repo memories\nlearning_mine_own.md learning_shared_seed.md"
+}
diff --git a/tests/harness.ts b/tests/harness.ts
new file mode 100644
index 0000000..ede7f36
--- /dev/null
+++ b/tests/harness.ts
@@ -0,0 +1,417 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { hostname, tmpdir, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export type HookName = "pull" | "autopush" | "announce";
+
+const HOOK_FILE: Record<HookName, string> = {
+	pull: "pull.mts",
+	autopush: "autopush.mts",
+	announce: "announce.mts",
+};
+
+const EVENT: Record<HookName, string> = {
+	pull: "SessionStart",
+	autopush: "Stop",
+	announce: "PostToolUse",
+};
+
+const GOLDEN_DIR = join(REPO, "tests", "golden");
+const slug = (name: string): string => name.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase();
+
+/**
+ * Goldens outlive the run that recorded them, so anything that varies by
+ * machine, day or temp path is replaced by a placeholder. Everything else
+ * stays byte-exact.
+ */
+export function normalizeRun(r: RunResult, root: string): RunResult {
+	const host = hostname().split(".")[0] ?? "";
+	const user = userInfo().username;
+	const scrub = (t: string): string =>
+		t
+			.split(root)
+			.join("<TMP>")
+			.replace(/\.memories-migration-\d{8}-\d{6}/g, ".memories-migration-<TS>")
+			.replace(/\(last modified [^)]*\)/g, "(last modified <REL>)")
+			.replace(/\d{4}-\d{2}-\d{2}/g, "<DATE>")
+			.replace(/(deleted by )[0-9a-f]{7,40}/g, "$1<SHA>")
+			.split(host)
+			.join("<HOST>")
+			.split(user)
+			.join("<USER>");
+	return { stdout: scrub(r.stdout), stderr: scrub(r.stderr), code: r.code, git: scrub(r.git) };
+}
+
+export function readGolden(name: string): RunResult | null {
+	try {
+		return JSON.parse(readFileSync(join(GOLDEN_DIR, `${slug(name)}.json`), "utf8")) as RunResult;
+	} catch {
+		return null;
+	}
+}
+
+export function writeGolden(name: string, r: RunResult): void {
+	mkdirSync(GOLDEN_DIR, { recursive: true });
+	writeFileSync(join(GOLDEN_DIR, `${slug(name)}.json`), `${JSON.stringify(r, null, 2)}\n`);
+}
+
+export type RunResult = {
+	readonly stdout: string;
+	readonly stderr: string;
+	readonly code: number;
+	readonly git: string;
+};
+
+export type Fixture = {
+	readonly name: string;
+	readonly hook: HookName;
+	readonly env?: Readonly<Record<string, string>>;
+	readonly stdin?: string;
+	/** Mutates the memories checkout to produce the pending state under test. */
+	readonly setup?: (repo: string, project: string) => void;
+	/** Runs before each implementation, after the tree is restored. */
+	readonly beforeEach?: (repo: string, project: string) => void;
+	/** Number of back-to-back invocations; the last one is compared. */
+	readonly runs?: number;
+	/** Mutates state between invocations, so a reprint-on-change can be exercised. */
+	readonly betweenRuns?: (repo: string, project: string) => void;
+	/** Non-vacuity: the bash side must actually produce this, or the fixture proves nothing. */
+	readonly expect?: RegExp;
+	/** The abort diagnostic is a documented stderr-only deviation; compare the rest of stderr. */
+	readonly abortsDiffer?: boolean;
+};
+
+/**
+ * Fixture commits are stamped at a fixed past date. `%cr` renders relative to
+ * NOW, so commits made "just now" render as "0 seconds ago" for one run and
+ * "1 second ago" for the other — an intermittent diff with no defect behind it.
+ */
+const FIXTURE_DATE = "2026-01-15T12:00:00+00:00";
+
+/**
+ * Nothing the suite compares may depend on the developer's environment.
+ *
+ * `LC_ALL` was deliberately left unpinned while the bash was still the reference:
+ * `LC_ALL=C` switches `${var:0:80}` from characters to bytes, so pinning it would
+ * have moved the reference rather than steadied it, and the truncation fixtures
+ * said so immediately. The bash is gone and the goldens are recordings now, so
+ * all the locale still reaches is git's own prose and collation -- and five
+ * goldens quote git's English verbatim, which a translated git breaks.
+ */
+const HERMETIC = {
+	LC_ALL: "C",
+	GIT_CONFIG_GLOBAL: "/dev/null",
+	GIT_CONFIG_SYSTEM: "/dev/null",
+	GIT_AUTHOR_NAME: "Fixture",
+	GIT_AUTHOR_EMAIL: "fixture@example.com",
+	GIT_COMMITTER_NAME: "Fixture",
+	GIT_COMMITTER_EMAIL: "fixture@example.com",
+	GIT_AUTHOR_DATE: FIXTURE_DATE,
+	GIT_COMMITTER_DATE: FIXTURE_DATE,
+} as const;
+
+/**
+ * `tsconfig.json` is JSONC by convention and `JSON.parse` is not, so reading it
+ * strictly means a comment or a trailing comma turns a coverage gate into a
+ * parse error that names neither. Scans in one pass so that `//`, `/*` and a
+ * trailing `,` inside a string literal are left alone.
+ */
+export function stripJsonComments(text: string): string {
+	const out: string[] = [];
+	let inString = false;
+	let inLine = false;
+	let inBlock = false;
+
+	for (let i = 0; i < text.length; i++) {
+		const c = text[i] as string;
+		const next = text[i + 1];
+
+		if (inLine) {
+			if (c === "\n") {
+				inLine = false;
+				out.push(c);
+			}
+			continue;
+		}
+		if (inBlock) {
+			if (c === "*" && next === "/") {
+				inBlock = false;
+				i++;
+			}
+			continue;
+		}
+		if (inString) {
+			out.push(c);
+			if (c === "\\") {
+				out.push(text[i + 1] ?? "");
+				i++;
+			} else if (c === '"') {
+				inString = false;
+			}
+			continue;
+		}
+		if (c === '"') {
+			inString = true;
+			out.push(c);
+			continue;
+		}
+		if (c === "/" && next === "/") {
+			inLine = true;
+			i++;
+			continue;
+		}
+		if (c === "/" && next === "*") {
+			inBlock = true;
+			i++;
+			continue;
+		}
+		// A structural comma before a closer. Walking back over whitespace can only
+		// reach a comma that is structural: a comma ending a string is followed by
+		// that string's own closing quote, never by `}` or `]`.
+		if (c === "}" || c === "]") {
+			let j = out.length - 1;
+			while (j >= 0 && /\s/.test(out[j] as string)) j--;
+			if (j >= 0 && out[j] === ",") out.splice(j, 1);
+		}
+		out.push(c);
+	}
+	return out.join("");
+}
+
+const entries = (dir: string): string[] => {
+	try {
+		return readdirSync(dir).sort();
+	} catch {
+		return [];
+	}
+};
+
+export const git = (cwd: string, ...args: string[]): string => {
+	try {
+		return execFileSync("git", args, {
+			cwd,
+			encoding: "utf8",
+			maxBuffer: Infinity,
+			stdio: ["ignore", "pipe", "pipe"],
+			env: { ...process.env, ...HERMETIC },
+		}).trim();
+	} catch {
+		return "";
+	}
+};
+
+/** A remote that rejects every push with exit 1, so the retry budget is actually spent. */
+export function rejectAllPushes(remote: string): void {
+	const hook = join(remote, "hooks", "pre-receive");
+	writeFileSync(hook, "#!/bin/sh\nexit 1\n");
+	chmodSync(hook, 0o755);
+}
+
+export const memory = (repo: string, name: string, body = "A shared lesson.\n"): string => {
+	const path = join(repo, "memories", name);
+	writeFileSync(path, body);
+	return path;
+};
+
+/** A bare remote plus a checkout with one committed memory, tracking origin. */
+export function makeProject(): { root: string; work: string; project: string; repo: string; remote: string } {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "sm-")));
+	const work = join(root, "work");
+	mkdirSync(work, { recursive: true });
+	const remote = join(work, "remote.git");
+	const project = join(work, "project");
+	const repo = join(project, ".claude", ".memories-repo");
+
+	execFileSync("git", ["init", "-q", "--bare", "-b", "main", remote]);
+	mkdirSync(join(repo, "memories"), { recursive: true });
+	git(repo, "init", "-q", "-b", "main");
+	git(repo, "config", "user.email", "t@example.com");
+	git(repo, "config", "user.name", "Test");
+	git(repo, "remote", "add", "origin", remote);
+	memory(repo, "learning_seed_topic.md", "Seed memory.\n");
+	git(repo, "add", "-A");
+	git(repo, "commit", "-qm", "seed");
+	git(repo, "push", "-q", "-u", "origin", "main");
+
+	// The ancestor Node resolves module type from. "commonjs" is the hostile case.
+	writeFileSync(join(project, "package.json"), '{"name":"consumer","type":"commonjs"}\n');
+	mkdirSync(join(project, ".claude", "hooks", "shared-memories"), { recursive: true });
+	execFileSync("ln", ["-sfn", ".memories-repo/memories", join(project, ".claude", "memories")]);
+	return { root, work, project, repo, remote };
+}
+
+/** The layout mcs produces: the entry point, and the library beside it. */
+function install(project: string, hook: HookName): void {
+	const hooks = join(project, ".claude", "hooks", "shared-memories");
+	mkdirSync(hooks, { recursive: true });
+	cpSync(join(REPO, "runtime", HOOK_FILE[hook]), join(hooks, HOOK_FILE[hook]));
+	chmodSync(join(hooks, HOOK_FILE[hook]), 0o755);
+	cpSync(join(REPO, "runtime", "lib"), join(hooks, "lib"), { recursive: true });
+}
+
+/** Executed directly. mcs prefixes the declared `hookInterpreter` instead, which
+ *  manifest.test.ts pins to the same command as the shebang, so the two agree. */
+function invoke(project: string, hook: HookName, fx: Fixture): Omit<RunResult, "git"> {
+	const payload = fx.stdin ?? JSON.stringify({ hook_event_name: EVENT[hook], session_id: "s1", cwd: project });
+	const r = spawnSync(join(project, ".claude", "hooks", "shared-memories", HOOK_FILE[hook]), [], {
+		cwd: project,
+		input: payload,
+		encoding: "utf8",
+		maxBuffer: Infinity,
+		timeout: 180_000,
+		env: { ...process.env, ...HERMETIC, ...fx.env },
+	});
+	return { stdout: r.stdout ?? "", stderr: r.stderr ?? "", code: r.status ?? -1 };
+}
+
+export function gitState(repo: string): string {
+	const upstream = git(repo, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}");
+	return [
+		// Repo-wide, deliberately: a snapshot scoped to memories/ is blind to the
+		// root-level damage the `-- memories/` pathspec exists to prevent.
+		`status-all: ${git(repo, "status", "--porcelain").split("\n").filter(Boolean).sort().join(" | ")}`,
+		`log-all: ${git(repo, "log", "--format=%s").split("\n").filter(Boolean).join(" | ")}`,
+		`tracked-all: ${git(repo, "ls-files").split("\n").filter(Boolean).sort().join(" | ")}`,
+		`status: ${git(repo, "status", "--porcelain", "--", "memories/").split("\n").filter(Boolean).sort().join(" | ")}`,
+		`log: ${git(repo, "log", "--format=%s", "--", "memories/").split("\n").filter(Boolean).join(" | ")}`,
+		`upstream: ${upstream || "(none)"}`,
+		`unpushed: ${upstream ? git(repo, "rev-list", "@{u}..HEAD", "--count") : "0"}`,
+		`tracked: ${git(repo, "ls-files", "--", "memories/").split("\n").filter(Boolean).sort().join(" | ")}`,
+		`review-shown: ${existsSync(join(repo, ".review-shown")) ? "present" : "absent"}`,
+		`worktree: ${entries(join(repo, "memories")).join(" ")}`,
+		`remote-log: ${git(repo, "log", "--format=%s", "origin/main").split("\n").filter(Boolean).join(" | ")}`,
+		`remote-files: ${git(repo, "ls-tree", "-r", "--name-only", "origin/main").split("\n").filter(Boolean).sort().join(" | ")}`,
+	].join("\n");
+}
+
+export function runHook(fx: Fixture): RunResult {
+	const { root, project, repo } = makeProject();
+	try {
+		fx.setup?.(repo, project);
+		install(project, fx.hook);
+		fx.beforeEach?.(repo, project);
+		let last = invoke(project, fx.hook, fx);
+		for (let i = 1; i < (fx.runs ?? 1); i++) {
+			fx.betweenRuns?.(repo, project);
+			last = invoke(project, fx.hook, fx);
+		}
+		return normalizeRun({ ...last, git: gitState(repo) }, root);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+}
+
+export type ScriptName = "doctor-memories" | "doctor-memories-remote";
+
+export type ScriptFixture = {
+	readonly name: string;
+	readonly script: ScriptName;
+	readonly setup?: (repo: string, project: string) => void;
+	readonly expectCode?: number;
+};
+
+/**
+ * Pack scripts are executed by mcs directly (ScriptRunner passes no arguments and
+ * chmods first), so here the shebang really is what selects the interpreter —
+ * unlike hooks, which mcs runs through their declared `hookInterpreter`.
+ */
+export function runScript(fx: ScriptFixture): RunResult {
+	const { root, project, repo } = makeProject();
+	try {
+		fx.setup?.(repo, project);
+		const r = spawnSync(join(REPO, "scripts", `${fx.script}.ts`), [], {
+			encoding: "utf8",
+			maxBuffer: Infinity,
+			timeout: 180_000,
+			env: { ...process.env, ...HERMETIC, MCS_PROJECT_PATH: project },
+		});
+		return normalizeRun(
+			{ stdout: r.stdout ?? "", stderr: r.stderr ?? "", code: r.status ?? -1, git: gitState(repo) },
+			root,
+		);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+}
+
+export type ConfigureFixture = {
+	readonly name: string;
+	/** Seeds the bare remote through a scratch clone before the project is shaped. */
+	readonly seed?: (clone: string) => void;
+	/** Shapes <project>/.claude before configure runs. */
+	readonly pre?: (project: string, claude: string) => void;
+	readonly env?: Readonly<Record<string, string>>;
+	readonly expectCode?: number;
+	readonly expect?: RegExp;
+	/** Seed a remote whose branch carries no memories/ tree at all. */
+	readonly emptyRemote?: boolean;
+	/** Pass MCS_PROJECT_PATH with a trailing slash; bash concatenates, join() would normalise. */
+	readonly trailingSlash?: boolean;
+	/** Skipped when running as root, where the fixture's premise does not hold. */
+	readonly skipAsRoot?: boolean;
+	/**
+	 * A deliberate departure from the recorded bash behaviour. The golden keeps
+	 * recording what the bash did; this states what we now do instead, and why.
+	 */
+	readonly deviation?: {
+		readonly reason: string;
+		readonly stdout?: (recorded: string) => string;
+		readonly code?: number;
+	};
+};
+
+/** The migration backup embeds a HH:MM:SS stamp, so the two runs cannot share it. */
+export function runConfigure(fx: ConfigureFixture): RunResult {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "sm-cfg-")));
+	try {
+		const work = join(root, "work");
+		mkdirSync(work, { recursive: true });
+		const remote = join(work, "remote.git");
+		const project = join(work, "project");
+		const claude = join(project, ".claude");
+
+		execFileSync("git", ["init", "-q", "--bare", "-b", "main", remote]);
+		const scratch = join(work, "scratch");
+		git(work, "clone", "-q", remote, scratch);
+		git(scratch, "config", "user.email", "t@example.com");
+		git(scratch, "config", "user.name", "Test");
+		if (fx.emptyRemote === true) {
+			writeFileSync(join(scratch, "README.md"), "no memories dir\n");
+		} else {
+			mkdirSync(join(scratch, "memories"), { recursive: true });
+			writeFileSync(join(scratch, "memories", "learning_shared_seed.md"), "Shared seed.\n");
+		}
+		git(scratch, "add", "-A");
+		git(scratch, "commit", "-qm", "seed");
+		git(scratch, "push", "-q", "-u", "origin", "main");
+		fx.seed?.(scratch);
+		rmSync(scratch, { recursive: true, force: true });
+
+		mkdirSync(claude, { recursive: true });
+		fx.pre?.(project, claude);
+
+		const r = spawnSync(join(REPO, "scripts", "configure-memories.ts"), [], {
+			encoding: "utf8",
+			timeout: 180_000,
+			env: {
+				...process.env,
+				...HERMETIC,
+				MCS_PROJECT_PATH: fx.trailingSlash === true ? `${project}/` : project,
+				MCS_RESOLVED_MEMORIES_REPO_URL: remote,
+				MCS_RESOLVED_MEMORIES_BRANCH: "main",
+				...fx.env,
+			},
+		});
+		const listing = `${entries(claude).join(" ")}\n${entries(join(claude, "memories")).join(" ")}`;
+		return normalizeRun(
+			{ stdout: r.stdout ?? "", stderr: r.stderr ?? "", code: r.status ?? -1, git: listing.trim() },
+			root,
+		);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+}
diff --git a/tests/manifest.test.ts b/tests/manifest.test.ts
new file mode 100644
index 0000000..3d3a10e
--- /dev/null
+++ b/tests/manifest.test.ts
@@ -0,0 +1,137 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ALLOWED_PATTERN } from "../runtime/lib/naming.mts";
+import { stripJsonComments } from "./harness.ts";
+
+const REPO = dirname(dirname(fileURLToPath(import.meta.url)));
+const manifest = readFileSync(join(REPO, "techpack.yaml"), "utf8");
+
+/** Every `source:` the manifest names, without pulling in a YAML dependency. */
+const sources = [...manifest.matchAll(/^\s*(?:source|contentFile|settingsFile|script|command|fixScript):\s*(\S+)/gm)]
+	.map((m) => m[1] as string)
+	.filter((v) => v.includes("/") || v.endsWith(".yaml"));
+
+describe("techpack manifest", () => {
+	test("every referenced path exists in the pack", () => {
+		const missing = sources.filter((s) => !existsSync(join(REPO, s)));
+		assert.deepEqual(missing, [], `manifest references files that do not exist: ${missing.join(", ")}`);
+		assert.ok(sources.length >= 8, `expected the manifest to reference several files, found ${sources.length}`);
+	});
+
+	test("every hook declares the interpreter mcs runs it with", () => {
+		// `.mts` is in mcs's ambiguousExtensions, so without this it falls back to bash.
+		const declared = manifest.match(/hookInterpreter: node --experimental-strip-types/g) ?? [];
+		assert.equal(declared.length, 3, "each of the three hooks needs its own hookInterpreter");
+		assert.match(manifest, /minMCSVersion: "2026\.9\.3"/, "the interpreter field needs the release that honours it");
+	});
+
+	test("jq is gone and node is declared", () => {
+		assert.doesNotMatch(manifest, /brew: jq/, "the pack no longer shells out to jq");
+		assert.match(manifest, /brew: node/, "the pack now depends on Node");
+	});
+
+	test("the library ships beside the hooks it is imported from", () => {
+		assert.match(manifest, /fileType: generic/);
+		assert.match(manifest, /source: runtime\/lib\n\s*destination: hooks\/shared-memories\/lib/);
+	});
+
+	test("the library destination tracks the pack identifier", () => {
+		// Hooks are namespaced into <pack-id>/, and the generic copy has to land in
+		// the same directory. Renaming the pack without this line breaks the imports.
+		const id = /^identifier:\s*(\S+)/m.exec(manifest)?.[1];
+		assert.ok(id, "the manifest declares no identifier");
+		assert.match(manifest, new RegExp(`destination: hooks/${id}/lib`));
+	});
+});
+
+describe("hook install contract", () => {
+	const dests = [...manifest.matchAll(/destination:\s*(\S+\.mts)/g)].map((m) => m[1] as string);
+
+	test("three hooks are registered, all TypeScript", () => {
+		assert.equal(dests.length, 3, "expected three registered hook entry points");
+		for (const d of dests) assert.ok(existsSync(join(REPO, "runtime", d)), `${d} is registered but not shipped`);
+	});
+
+	test("no shell survives anywhere in the pack", () => {
+		const stray = readdirSync(REPO, { recursive: true, encoding: "utf8" }).filter(
+			(f) => f.endsWith(".sh") && !f.startsWith("node_modules"),
+		);
+		assert.deepEqual(stray, [], `shell scripts are not permitted: ${stray.join(", ")}`);
+	});
+
+	test("every entry point carries a shebang matching its declared interpreter", () => {
+		for (const d of dests) {
+			const first = readFileSync(join(REPO, "runtime", d), "utf8").split("\n")[0];
+			assert.equal(
+				first,
+				"#!/usr/bin/env -S node --experimental-strip-types --disable-warning=ExperimentalWarning",
+				`${d} has no usable shebang`,
+			);
+		}
+	});
+
+	test("every entry point is executable", () => {
+		for (const d of dests) {
+			// mcs chmods on install, but a non-executable file in the repo is a smell.
+			assert.ok(statSync(join(REPO, "runtime", d)).mode & 0o111, `${d} is not executable`);
+		}
+	});
+
+	test("every entry point imports its library as a sibling", () => {
+		// `./lib/...` has to resolve both in the pack checkout and once installed.
+		for (const d of dests) {
+			const body = readFileSync(join(REPO, "runtime", d), "utf8");
+			assert.doesNotMatch(body, /from "\.\.\//, `${d} reaches outside its own directory`);
+			assert.match(body, /from "\.\/lib\//, `${d} does not import the shared library`);
+		}
+	});
+
+	test("every entry point is under the typecheck", () => {
+		// This was `node --check`, which is parse-only and, on the declared 22.6.0
+		// floor, does not apply the `.mts`-implies-ESM mapping: it read every entry
+		// point as CommonJS and died on the first import. `tsc` subsumes it, but only
+		// if `include` reaches these files -- a pattern ending in `.ts` matches no
+		// `.mts`, which left all three plus lib/paths.mts unchecked entirely.
+		const include = JSON.parse(stripJsonComments(readFileSync(join(REPO, "tsconfig.json"), "utf8"))).include as string[];
+		// Resolve the globs instead of pinning one pattern string: rewriting
+		// `include`, or adding a runtime file, then still has to keep the coverage.
+		const reaches = include.map(
+			(p) =>
+				new RegExp(
+					`^${p
+						.split("/")
+						.map((s) => (s === "**" ? "\0" : s.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*")))
+						.join("/")
+						.replace(/\0\//g, "(?:[^/]+/)*")}$`,
+				),
+		);
+		const unreachable = readdirSync(join(REPO, "runtime"), { recursive: true, encoding: "utf8" })
+			.filter((f) => f.endsWith(".ts") || f.endsWith(".mts"))
+			// readdirSync yields the platform separator; the globs are written with "/".
+			.map((f) => `runtime/${f.split(sep).join("/")}`)
+			.filter((f) => !reaches.some((re) => re.test(f)));
+		assert.deepEqual(unreachable, [], `tsconfig include does not reach: ${unreachable.join(", ")}`);
+	});
+});
+
+describe("the naming rule has one definition", () => {
+	test("the slash command documents the pattern the code enforces", () => {
+		const cmd = readFileSync(join(REPO, "commands", "approve-memories.md"), "utf8");
+		const m = /\^memories\/\(learning\|decision\)_\[a-zA-Z0-9_-\]\+\\\.md\$/.exec(cmd);
+		assert.ok(m, "approve-memories.md no longer documents the guardrail pattern");
+		assert.equal(ALLOWED_PATTERN.source, "^memories\\/(learning|decision)_[a-zA-Z0-9_-]+\\.md$");
+	});
+
+	test("nothing shipped still points at a second copy of the rule", () => {
+		// commands/ ships to consumers and Claude reads it, so it counts as much as the code.
+		for (const dir of ["runtime", "runtime/lib", "scripts", "commands", "templates"]) {
+			for (const f of readdirSync(join(REPO, dir)).filter((n) => /\.(m?ts|md)$/.test(n))) {
+				const body = readFileSync(join(REPO, dir, f), "utf8");
+				assert.doesNotMatch(body, /keep in sync/i, `${dir}/${f} still points at a second copy`);
+			}
+		}
+	});
+});
diff --git a/tests/scripts.test.ts b/tests/scripts.test.ts
new file mode 100644
index 0000000..0698dd0
--- /dev/null
+++ b/tests/scripts.test.ts
@@ -0,0 +1,86 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { rmSync, symlinkSync, mkdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { git, readGolden, runScript, type RunResult, type ScriptFixture } from "./harness.ts";
+
+
+/**
+ * Behaviour is pinned to tests/golden/, recorded from the bash implementation
+ * this pack replaced and verified against it fixture by fixture before the bash
+ * was removed. A drift here is a change in what the pack does, not a stale test.
+ */
+function check(name: string, actual: RunResult, expect?: RegExp): void {
+	const golden = readGolden(name);
+	assert.ok(golden, `no golden recorded for "${name}"`);
+	assert.equal(actual.stdout, golden.stdout, `stdout drifted from recorded behaviour for "${name}"`);
+	assert.equal(actual.code, golden.code, `exit code drifted for "${name}"`);
+	assert.equal(actual.stderr, golden.stderr, `stderr drifted from recorded behaviour for "${name}"`);
+	assert.equal(actual.git, golden.git, `resulting state drifted for "${name}"\ngolden:\n${golden.git}\n\nactual:\n${actual.git}`);
+	// A fixture where nothing happens passes vacuously, so pin what was recorded.
+	if (expect) assert.match(golden.stdout + golden.stderr, expect, `fixture "${name}" never exercised what it claims to`);
+}
+
+function assertParity(fx: ScriptFixture): void {
+	check(fx.name, runScript(fx));
+	if (fx.expectCode !== undefined) {
+		assert.equal((readGolden(fx.name) as RunResult).code, fx.expectCode, `fixture "${fx.name}" did not reach the state it claims`);
+	}
+}
+
+const claude = (project: string) => join(project, ".claude");
+
+const fixtures: readonly ScriptFixture[] = [
+	{ name: "doctor: healthy setup passes", script: "doctor-memories", expectCode: 0 },
+	{
+		name: "doctor: missing checkout and symlink",
+		script: "doctor-memories",
+		expectCode: 1,
+		setup: (repo, project) => {
+			rmSync(repo, { recursive: true, force: true });
+			unlinkSync(join(claude(project), "memories"));
+		},
+	},
+	{
+		name: "doctor: checkout present, symlink missing",
+		script: "doctor-memories",
+		expectCode: 1,
+		setup: (_repo, project) => unlinkSync(join(claude(project), "memories")),
+	},
+	{
+		name: "doctor: dangling symlink",
+		script: "doctor-memories",
+		expectCode: 1,
+		setup: (repo, project) => {
+			rmSync(repo, { recursive: true, force: true });
+		},
+	},
+	{
+		name: "doctor: symlink resolves somewhere that is not a checkout",
+		script: "doctor-memories",
+		expectCode: 1,
+		setup: (_repo, project) => {
+			const link = join(claude(project), "memories");
+			unlinkSync(link);
+			mkdirSync(join(project, "elsewhere"), { recursive: true });
+			symlinkSync(join(project, "elsewhere"), link);
+		},
+	},
+	{ name: "doctor-remote: reachable remote passes", script: "doctor-memories-remote", expectCode: 0 },
+	{
+		name: "doctor-remote: no checkout skips",
+		script: "doctor-memories-remote",
+		expectCode: 3,
+		setup: (repo) => rmSync(repo, { recursive: true, force: true }),
+	},
+	{
+		name: "doctor-remote: unreachable remote warns",
+		script: "doctor-memories-remote",
+		expectCode: 2,
+		setup: (repo) => git(repo, "remote", "set-url", "origin", "/nonexistent/definitely-not-here.git"),
+	},
+];
+
+describe("pack scripts — behaviour is pinned", () => {
+	for (const fx of fixtures) test(fx.name, () => assertParity(fx));
+});
diff --git a/tests/unit.test.ts b/tests/unit.test.ts
new file mode 100644
index 0000000..1ac7f32
--- /dev/null
+++ b/tests/unit.test.ts
@@ -0,0 +1,180 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stripJsonComments } from "./harness.ts";
+import { isJsonStream } from "../runtime/lib/hook-io.mts";
+import { resolveMode } from "../runtime/lib/mode.mts";
+import { ALLOWED_PATTERN, MEMORY_WRITE_PATTERN } from "../runtime/lib/naming.mts";
+import { jitterMs, pushAttempts } from "../runtime/lib/push.mts";
+import { canonicalState, describe as describePending, hashState, lastShownHash, urlEncodePath } from "../runtime/lib/report.mts";
+import type { Pending } from "../runtime/lib/pending.mts";
+
+describe("mode resolution", () => {
+	for (const [raw, mode] of [[undefined, "auto"], ["", "auto"], ["auto", "auto"], ["full", "full"], ["review", "review"]] as const) {
+		test(`${JSON.stringify(raw)} resolves to ${mode}`, () => {
+			const r = resolveMode(raw);
+			assert.equal(r.mode, mode);
+			assert.equal(r.unrecognised, null);
+		});
+	}
+	test("an unrecognised value falls back to auto and is reported", () => {
+		assert.deepEqual(resolveMode("banana"), { mode: "auto", unrecognised: "banana" });
+	});
+});
+
+describe("the naming guardrail", () => {
+	const ok = ["memories/learning_a_b.md", "memories/decision_x-y_z.md", "memories/learning_A1_b2.md"];
+	const bad = [
+		"memories/scratch.md",
+		"memories/learning_a b.md",
+		"memories/learning_a.txt",
+		"memories/sub/learning_a_b.md",
+		"learning_a_b.md",
+		"memories/learning_.md",
+	];
+	for (const f of ok) test(`accepts ${f}`, () => assert.ok(ALLOWED_PATTERN.test(f)));
+	for (const f of bad) test(`rejects ${f}`, () => assert.ok(!ALLOWED_PATTERN.test(f)));
+
+	test("the write pattern anchors on .claude/memories at any depth", () => {
+		assert.ok(MEMORY_WRITE_PATTERN.test("/a/b/.claude/memories/learning_a_b.md"));
+		assert.ok(MEMORY_WRITE_PATTERN.test(".claude/memories/decision_a_b.md"));
+		assert.ok(!MEMORY_WRITE_PATTERN.test("/a/notes/learning_a_b.md"));
+	});
+});
+
+describe("the retry budget", () => {
+	for (const [raw, n] of [[undefined, 12], ["", 12], ["banana", 12], ["-1", 12], ["3.5", 12], ["0", 1], ["1", 1], ["7", 7]] as const) {
+		test(`${JSON.stringify(raw)} yields ${n}`, () => assert.equal(pushAttempts(raw), n));
+	}
+	test("jitter is bounded by the doubling schedule and the 1.5s cap", () => {
+		for (let a = 1; a <= 12; a++) {
+			assert.equal(jitterMs(a, () => 1), Math.round(Math.min(0.05 * 2 ** a, 1.5) * 1000));
+			assert.equal(jitterMs(a, () => 0), 0);
+		}
+		assert.equal(jitterMs(12, () => 1), 1500, "the cap holds at the top of the schedule");
+	});
+});
+
+describe("file:// encoding", () => {
+	test("encodes only what breaks terminal autolinking", () => {
+		assert.equal(urlEncodePath("/a b/c#d?e"), "/a%20b/c%23d%3Fe");
+	});
+	test("leaves other reserved characters alone", () => {
+		assert.equal(urlEncodePath("/a(b)/c&d'e"), "/a(b)/c&d'e");
+	});
+});
+
+const pending = (over: Partial<Pending> = {}): Pending => ({
+	uncommitted: 0,
+	unpushed: 0,
+	untracked: [],
+	numstats: [],
+	deleted: [],
+	...over,
+});
+
+describe("review state", () => {
+	test("is stable regardless of the order files are discovered in", () => {
+		const a = canonicalState(pending({ untracked: ["memories/b.md", "memories/a.md"] }), "");
+		const b = canonicalState(pending({ untracked: ["memories/a.md", "memories/b.md"] }), "");
+		assert.equal(hashState(a), hashState(b));
+	});
+	test("distinguishes a new file from a modified one", () => {
+		const a = canonicalState(pending({ untracked: ["memories/a.md"] }), "");
+		const b = canonicalState(pending({ numstats: [{ added: "1", deleted: "0", path: "memories/a.md" }] }), "");
+		assert.notEqual(hashState(a), hashState(b));
+	});
+	test("ignores content, so re-editing the same file does not reprint", () => {
+		assert.equal(
+			canonicalState(pending({ untracked: ["memories/a.md"] }), ""),
+			canonicalState(pending({ untracked: ["memories/a.md"] }), ""),
+		);
+	});
+	test("an unpushed commit contributes only when HEAD resolves", () => {
+		assert.equal(canonicalState(pending({ unpushed: 2 }), ""), "");
+		assert.match(canonicalState(pending({ unpushed: 2 }), "abc123"), /^UNPUSHED\tabc123\t2$/);
+	});
+	test("the digest is sha256, matching `shasum -a 256`", () => {
+		assert.equal(hashState(""), "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
+	});
+});
+
+describe("the pending description", () => {
+	test("names files and commits separately", () => {
+		assert.equal(describePending(2, 3), "2 pending file(s) in memories/ and 3 unpushed commit(s)");
+		assert.equal(describePending(2, 0), "2 pending file(s) in memories/");
+		assert.equal(describePending(0, 3), "3 unpushed commit(s)");
+	});
+});
+
+describe("the jq stdin gate", () => {
+	for (const s of ["", "   ", "\n", "null", "42", '"s"', "{}", "{}{}", '{"a":1} {"b":2}', "[1,2]", '{"a":"}"}']) {
+		test(`accepts ${JSON.stringify(s)}`, () => assert.ok(isJsonStream(s)));
+	}
+	for (const s of ["not json", "{", "}", "[1,", '{"a":1} x', '"unterminated']) {
+		test(`rejects ${JSON.stringify(s)}`, () => assert.ok(!isJsonStream(s)));
+	}
+});
+
+describe("the review dedupe state fails open", () => {
+	test("an unreadable state file means no dedupe rather than a lost report", () => {
+		const dir = mkdtempSync(join(tmpdir(), "sm-dedupe-"));
+		try {
+			// A directory where the file belongs: readFileSync throws EISDIR, which used
+			// to escape into failOpen and swallow the entire review report. The bash read
+			// it as `tr ... 2>/dev/null || true` and simply printed.
+			const asDir = join(dir, "state-is-a-directory");
+			mkdirSync(asDir);
+			assert.equal(lastShownHash(asDir), "");
+
+			// The racy case: a concurrent Stop hook removed it after the existsSync.
+			assert.equal(lastShownHash(join(dir, "never-existed")), "");
+
+			// And it still reads a real one, `tr -d '[:space:]'` and all.
+			writeFileSync(join(dir, "shown"), "  deadbeef\n");
+			assert.equal(lastShownHash(join(dir, "shown")), "deadbeef");
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("reading tsconfig.json as the JSONC it is by convention", () => {
+	const parse = (t: string): unknown => JSON.parse(stripJsonComments(t));
+
+	test("line and block comments are removed", () => {
+		assert.deepEqual(parse('{\n  // leading\n  "a": 1, /* inline */ "b": 2\n}'), { a: 1, b: 2 });
+	});
+
+	test("a block comment spanning lines is removed", () => {
+		assert.deepEqual(parse('{\n  /*\n   * why this option is set\n   */\n  "a": 1\n}'), { a: 1 });
+	});
+
+	test("comment markers inside a string survive", () => {
+		assert.deepEqual(parse('{"a": "https://x/y", "b": "/* not a comment */"}'), {
+			a: "https://x/y",
+			b: "/* not a comment */",
+		});
+	});
+
+	test("an escaped quote does not end the string early", () => {
+		assert.deepEqual(parse('{"a": "he said \\"hi\\" // still a string"}'), { a: 'he said "hi" // still a string' });
+	});
+
+	test("trailing commas before a closer are dropped", () => {
+		assert.deepEqual(parse('{"a": [1, 2, ], "b": 2, }'), { a: [1, 2], b: 2 });
+	});
+
+	test("a comma inside a string is not mistaken for a trailing one", () => {
+		assert.deepEqual(parse('{"a": "x,", "b": ["y,"]}'), { a: "x,", b: ["y,"] });
+	});
+
+	test("the pack's own tsconfig still parses and declares include", () => {
+		const repo = dirname(dirname(fileURLToPath(import.meta.url)));
+		const cfg = parse(readFileSync(join(repo, "tsconfig.json"), "utf8")) as { include?: string[] };
+		assert.ok(Array.isArray(cfg.include) && cfg.include.length > 0, "tsconfig declares no include");
+	});
+});
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..c791561
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["runtime/**/*.mts", "runtime/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
+}