From 9e2a563059eb2a7ed101995633672ded6a635fcd Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 12:12:14 -0700
Subject: [PATCH 01/20] docs: multi-recipient age encryption design spec
 (EGB-283)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...4-multi-recipient-age-encryption-design.md | 230 ++++++++++++++++++
 1 file changed, 230 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-24-multi-recipient-age-encryption-design.md

diff --git a/docs/superpowers/specs/2026-06-24-multi-recipient-age-encryption-design.md b/docs/superpowers/specs/2026-06-24-multi-recipient-age-encryption-design.md
new file mode 100644
index 0000000..2141dea
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-24-multi-recipient-age-encryption-design.md
@@ -0,0 +1,230 @@
+# EGB-283 — Multi-recipient age encryption
+
+**Date:** 2026-06-24
+**Issue:** [EGB-283](https://linear.app/egbt/issue/EGB-283) — secrets: multi-recipient age encryption (multiple keys per file)
+**Status:** Design approved, ready for implementation plan
+**Related:** EGB-281 (multi-store), EGB-677/EGB-703 (manifest + store-format v2)
+
+## Problem
+
+Today every blob in a store is encrypted to exactly one age public key (`age -r "$pubkey"`,
+where `$pubkey` is derived from the store's single `key.txt`). The whole team shares one
+private key. EGB-281's multi-store work lets users separate work/personal/client secrets into
+different stores, each with its own key — but *within* a single store there is still only one key,
+so onboarding/offboarding a teammate means sharing or rotating one secret by hand.
+
+age natively supports multiple recipients: `age -r KEY1 -r KEY2 -o file.age input` writes one
+recipient stanza per key, and any matching identity decrypts. This lets a single store have N
+members, each with their own keypair. Adding/removing a teammate becomes a re-encrypt against the
+current recipient set — no shared password.
+
+## Goals
+
+- A store can encrypt every blob to N recipient public keys.
+- Recipient set is managed with first-class commands (`secrets recipients add/rm/list`).
+- The recipient set is **singular and consistent per store**: every blob is always readable by
+  exactly the current set.
+- Fully backward compatible: existing single-key stores keep working untouched; the feature is
+  opt-in and detected by file presence (no store-format-marker bump).
+- Decryption path is unchanged (members use their own `key.txt`).
+
+## Non-goals (YAGNI — explicit scope cuts)
+
+- **SSH recipients** (`ssh-ed25519` / `ssh-rsa`). Native age X25519 keys cover the team-key use
+  case; SSH adds a parsing/format axis. Clean future follow-up.
+- **Per-file or per-project recipient subsets.** The whole store shares one recipient set.
+- **Key discovery / distribution.** Public keys are pasted in out of band, exactly as `key.txt`
+  is shared today.
+- **Merging recipients into a project-level config** (`.secrets.json` / `.secrets-files`). See
+  "Why recipients are not in the project manifest" below.
+
+## Design decisions (resolved during brainstorming)
+
+1. **Storage:** committed `recipients.txt` at the store root, managed via
+   `secrets recipients add/rm/list` subcommands.
+2. **Re-encrypt scope:** `add`/`rm` re-encrypt the **entire store immediately** to the new set in
+   one commit. The store is always consistent.
+3. **Backward compatibility:** absence of `recipients.txt` ⇒ exact current single-key behavior.
+   First `recipients add` on a legacy store bootstraps the file seeded with the local pubkey plus
+   the new key. `init` going forward seeds `recipients.txt` with the freshly generated pubkey
+   (born-multi).
+4. **`rekey` semantics:** on a multi-recipient store, `rekey` becomes "re-encrypt all to the
+   current `recipients.txt` set" (no new keypair). On a legacy store it keeps today's behavior
+   (generate a new keypair, re-encrypt to it). One shared re-encrypt engine.
+5. **Store config shape:** keep `recipients.txt` as its own plain, age-native file (jq-free),
+   alongside the existing one-line `.secrets-format` marker — matching the repo's
+   small-single-purpose-plain-file convention. Not folded into a JSON store-config.
+
+## Why recipients are not in the project manifest
+
+The tool has two config planes in two different git repos:
+
+| Plane       | Location                         | Files                                              | Scope                       |
+| ----------- | -------------------------------- | -------------------------------------------------- | --------------------------- |
+| **Project** | `$PWD` (the project's own repo)  | `.secrets.json` (absorbs legacy `.secrets-files`), `.secrets-store` | *What this project syncs*   |
+| **Store**   | `$SECRETS_DIR` (`~/.secrets`)    | `.secrets-format`, **`recipients.txt`** (new)      | *Metadata about the encrypted repo* |
+
+Recipients are **store-scoped** — who can decrypt *this store*, shared by every project in it.
+Putting them in a project-level manifest would let each project carry its own copy and **diverge**,
+the exact inconsistency the "always re-encrypt the whole store to one set" rule prevents. It also
+collides with the deliberate EGB-703 decision that *the store holds no project manifest*. So the
+recipient set lives with the store, next to `.secrets-format`.
+
+## `recipients.txt` format and security rails
+
+Lives at `$SECRETS_DIR/recipients.txt`, **committed** (public keys are not secret; the store
+`.gitignore` only blocks `key.txt` and plaintext env files, so the file is tracked automatically).
+age `-R` format: one recipient per line, `# comment` and blank lines allowed.
+
+```
+# alice (laptop)
+age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9qsxxxxxx
+# bob
+age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqxxxxxx
+```
+
+**We do not pass the file path to `age -R`.** A committed file is an injection surface, so the
+tool parses it itself into a validated indexed array `RECIPIENT_ARGS=(-r age1… -r age1…)`,
+mirroring the conservative posture of `.secrets-store` / `.secrets-files`:
+
+- Each non-comment, non-blank line (after trim) must match a native age X25519 recipient exactly:
+  `^age1[0-9a-z]{58}$`. Anything else — SSH recipients, shell metacharacters, whitespace inside the
+  token, control/ANSI characters, `-r`-injection look-alikes — is **rejected with a clear error**.
+  No shell expansion, ever.
+- A symlinked `recipients.txt` is refused (same rail as the manifests).
+- `--name` labels (written as `# <name>` comment lines above the key) are restricted to
+  `[A-Za-z0-9 ._-]`; anything else is rejected. This blocks comment-injection into the file.
+- The parser is pure bash (bash-3.2 safe). Indexed arrays are fine on bash 3.2; only *associative*
+  arrays are bash-4.
+
+Validation is the single source of truth — both the `recipients` subcommands and `_load_recipients`
+(below) route through the same validator, so an externally hand-edited malicious file is caught on
+the next encrypt, not just at `add` time.
+
+## Components
+
+### `_load_recipients()` — populate `RECIPIENT_ARGS`
+Called once per command that encrypts. Populates the global indexed array `RECIPIENT_ARGS`:
+
+- `recipients.txt` present → validated array of every key in the file (error out on any invalid
+  line; refuse an empty/all-comment file).
+- absent (legacy store) → `(-r <derived-local-pubkey>)`, identical to today's single-recipient
+  behavior.
+
+### `_reencrypt_all()` — shared re-encrypt engine
+Factored out of today's `cmd_rekey` decrypt→re-encrypt loop:
+
+1. Decrypt every `*.age` in the store (recursive `find -type f -name '*.age'`, covering nested
+   manifest dotenv blobs and `external/` blobs) with the local `key.txt` into a tmpdir. The
+   operator must be a current recipient; a decryption failure aborts with the old state preserved.
+2. Re-encrypt each file with `age "${RECIPIENT_ARGS[@]}"` back to its relpath.
+3. `ensure_store_protections`, `git add -A`, commit, push (if a remote exists).
+
+All recipient-changing paths call it:
+
+| Command                         | Behavior                                                              |
+| ------------------------------- | -------------------------------------------------------------------- |
+| `recipients add` / `rm`         | edit `recipients.txt` → `_load_recipients` → `_reencrypt_all`         |
+| `rekey` (multi-recipient store) | `_reencrypt_all` to current set, **no new keypair**                   |
+| `rekey` (legacy store)          | today's behavior: generate new keypair, set recipients to it, re-encrypt |
+| `reencrypt` (new, idempotent)   | `_reencrypt_all` — heal/backfill after a manual edit                  |
+
+### `secrets recipients` subcommand
+- `recipients list` — prints names + keys from `recipients.txt` (read-only, jq-free). On a legacy
+  store, prints the single derived pubkey with a "single-key (no recipients.txt)" note.
+- `recipients add <age1…> [--name <label>]` — validates the key, refuses duplicates, appends
+  (with the optional `# <label>` comment), bootstraps the file with `{local pubkey, new key}` if
+  the store is still legacy, then `_reencrypt_all`.
+- `recipients rm <age1…|name>` — removes the matching entry, then `_reencrypt_all`. **Guards:**
+  refuses to remove the last recipient; removing *your own* key (which would lock you out of future
+  pulls) requires `--yes`. Removal takes effect going forward — git history can't be un-shared
+  (documented, same caveat as today's `rekey`).
+
+### Encryption call-site changes
+Every existing `age -r "$pubkey" -o …` site becomes `age "${RECIPIENT_ARGS[@]}" -o …`:
+
+- `push_dir_to_project` (dotenv) and the nested manifest dotenv path
+- `push_external_files` (external `properties` and `file` blobs)
+- `cmd_init` (seeds the store; born-multi)
+- `cmd_rekey` re-encrypt loop (now `_reencrypt_all`)
+
+Functions that currently take `pubkey` as a positional arg are updated to rely on the
+`RECIPIENT_ARGS` global populated by `_load_recipients` at command entry, avoiding array-passing
+gymnastics on bash 3.2. **Decryption paths (`pull`, `verify`) are unchanged** — `age -d -i
+"$KEY_FILE"` already tries the identity against all recipient stanzas.
+
+### `init` / `which` / `verify` integration
+- **`init`** writes `recipients.txt` seeded with the freshly generated pubkey (born-multi), staged
+  like `.secrets-format`.
+- **`which`** prints a `recipients: N (alice, bob, …)` line, or `recipients: single-key (no
+  recipients.txt)` for a legacy store.
+- **`verify`** already decrypt-tests with the local key — works as-is for a member. **Added cheap
+  invariant:** count the `-> X25519` recipient stanzas in each blob header and assert it equals the
+  number of entries in `recipients.txt`. age exposes no way to list *which* recipients a file
+  targets (X25519 stanzas are ephemeral), so a count check is the strongest machine-checkable
+  invariant; full-identity consistency relies on the always-re-encrypt-all rule. The check is
+  skipped on legacy stores (no `recipients.txt`).
+
+## Data flow
+
+**Onboarding a teammate**
+1. Teammate runs `age-keygen` locally, sends their **public** key out of band.
+2. An existing member: `secrets recipients add age1theirpub --name them` → store re-encrypts to
+   `{existing…, them}` in one commit, pushed.
+3. Teammate clones the store repo, drops their own `key.txt` in place, and `secrets pull` works —
+   their key matches one stanza in every blob.
+
+**Offboarding**
+1. `secrets recipients rm them` → store re-encrypts to the remaining set, pushed. New blobs are no
+   longer readable by the removed key. (Historical git revisions remain readable by their old key —
+   rotate any still-sensitive secret values, same as today.)
+
+## Error handling
+
+- Invalid/duplicate key on `add` → reject before any re-encrypt; store untouched.
+- Invalid line discovered by `_load_recipients` during any encrypt → abort the command with a clear
+  pointer to the offending line; nothing written.
+- `_reencrypt_all` decryption failure (operator not a current recipient, or corrupt blob) → abort,
+  old store state preserved (mirrors today's `rekey` safety).
+- `rm` last recipient → refused. `rm` own key → requires `--yes`.
+- Empty/all-comment `recipients.txt` → treated as an error (a store with zero recipients can encrypt
+  nothing).
+
+## Testing
+
+New `test/recipients.bats` suite plus additions to existing suites:
+
+- **Happy path:** `init` born-multi; `add` bootstraps a legacy store; `add`/`rm` round-trip; a blob
+  encrypted to 3 keys decrypts with each of the 3 identities; `list` output; `rekey` on a
+  multi-recipient store keeps the set and generates no new key; `reencrypt` is idempotent.
+- **Backward compat:** a legacy store (no `recipients.txt`) still pushes/pulls/rekeys exactly as
+  before; an old single-key client decrypts a recipients.txt-store where its key is a recipient.
+- **`verify`:** stanza-count invariant passes on a healthy multi-recipient store and flags a blob
+  whose recipient count drifted.
+- **Security regression fixtures** (`recipients.txt` is a new committed attack surface): non-age /
+  malformed keys, shell metacharacters, control/ANSI characters, `-r`-injection look-alikes,
+  symlinked `recipients.txt`, bad `--name`, remove-last-recipient, remove-self-without-`--yes`.
+
+Per the repo security-review policy (`.ship-policy.json`, CLAUDE.md): these adversarial fixtures are
+written as **ordinary bats regression tests**, not AI red-team/adversarial-review passes. Before any
+ship/PR, the human operator runs `./test/run-security.sh` and completes the SIGNOFF prompt;
+`./test/run-security.sh` is operator-local and is **not** run on the user's behalf.
+
+## Backward compatibility / migration
+
+No store-format-marker bump. Multi-recipient is purely additive and detected by the **presence** of
+`recipients.txt`, mirroring the `.secrets-format` "absence implies v1" pattern. Existing stores keep
+working with zero action; a store becomes multi-recipient the first time `recipients add` (or `init`
+on a fresh store) writes `recipients.txt`.
+
+## Documentation
+
+- `CLAUDE.md` Architecture section: add a multi-recipient bullet (store-scoped `recipients.txt`,
+  `recipients` subcommand, shared `_reencrypt_all` engine, `rekey` dual semantics, security rails).
+- `README.md`: onboarding/offboarding a teammate; `recipients add/rm/list`.
+- Test counts in `CLAUDE.md` Project Structure updated.
+
+## Open questions
+
+None blocking. (SSH-recipient support and a JSON store-config remain possible future follow-ups,
+explicitly out of scope here.)

From 3a7eea55297b8bf3aa51d04fb5cf3ab7f3bc4b65 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 12:20:32 -0700
Subject: [PATCH 02/20] docs: multi-recipient age encryption implementation
 plan (EGB-283)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...26-06-24-multi-recipient-age-encryption.md | 1177 +++++++++++++++++
 1 file changed, 1177 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-24-multi-recipient-age-encryption.md

diff --git a/docs/superpowers/plans/2026-06-24-multi-recipient-age-encryption.md b/docs/superpowers/plans/2026-06-24-multi-recipient-age-encryption.md
new file mode 100644
index 0000000..96a1b3a
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-24-multi-recipient-age-encryption.md
@@ -0,0 +1,1177 @@
+# Multi-recipient age encryption Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let a single `secrets` store encrypt every blob to N age recipient public keys (a per-store team-key set) instead of one shared key, managed via `secrets recipients add/rm/list`, with full backward compatibility for existing single-key stores.
+
+**Architecture:** A committed, store-scoped `recipients.txt` (age `-R` format) holds the recipient set. A new `_load_recipients` parses + validates it into a global `RECIPIENT_ARGS=(-r k1 -r k2 …)` array that every encrypt site uses; absence of the file means legacy single-key behavior (`-r $(get_pubkey)`). A shared `_reencrypt_all` engine (factored from today's `rekey`) decrypts the whole store with the local key and re-encrypts to the current set, and is called by `recipients add/rm`, the new `reencrypt`, and multi-recipient `rekey`. Decryption is unchanged — each member uses their own `key.txt`.
+
+**Tech Stack:** Single POSIX-ish bash script (`secrets`), system bash 3.2 compatible (indexed arrays OK, NO associative arrays). `age` / `age-keygen` for crypto. `git` for the store. `bats-core` for tests. `jq` is NOT introduced anywhere in this feature (recipients.txt is plain text, keeping store ops jq-free).
+
+## Global Constraints
+
+- **bash 3.2 only:** no associative arrays, no bash-4 features. Indexed arrays (`RECIPIENT_ARGS=()`, `arr+=(x)`, `"${arr[@]}"`) are fine.
+- **bats `[[ ]]` gotcha:** every standalone `[[ … ]]` assertion in a test MUST end with `|| false`. Single-bracket `[ ]` is unaffected.
+- **age recipient format accepted:** native age X25519 only — `age1` + exactly 58 chars of `[0-9a-z]`. SSH recipients are out of scope (reject them). This regex/charset is also the injection rail: it cannot contain shell metacharacters, whitespace, or extra flags.
+- **`recipients.txt` is committed, NOT gitignored** (public keys are not secret). The store `.gitignore` only blocks `key.txt` and plaintext env files, so the file is tracked automatically — do not add it to `.gitignore`.
+- **Security-review policy (`.ship-policy.json`, CLAUDE.md):** adversarial fixtures in this plan are ordinary bats regression tests, NOT AI red-team passes. Do NOT run `./test/run-security.sh` on the user's behalf. Before ship, the human operator runs it and signs off.
+- **Re-encrypt invariant:** any change to the recipient set re-encrypts the WHOLE store in one commit. `RECIPIENT_ARGS` is always populated by `_load_recipients` before any `age "${RECIPIENT_ARGS[@]}"` call (never reference the array empty under `set -u`).
+- **Commit cadence:** one commit per task (TDD: test → impl → green → commit).
+
+## File map
+
+- `secrets` — all code changes (helpers, `recipients`/`reencrypt` commands, encrypt-site refactor, `init`/`which`/`verify`/`rekey` edits, dispatch + help).
+- `test/recipients.bats` — NEW suite for all multi-recipient behavior + security fixtures.
+- `CLAUDE.md`, `README.md` — docs + test counts.
+
+## Conventions referenced
+
+- Constants like `SECRETS_FILES_NAME=".secrets-files"` live ~line 360; `KEY_FILE` is set both as a global default (~line 20) and re-set inside `resolve_store` (~line 301). Mirror this for `RECIPIENTS_FILE`.
+- Existing encrypt sites (all `age -r "$pubkey" -o …`): `push_dir_to_project` (~1207), `cmd_push` inline (~1357), `push_external_files` (~655 and ~684), `cmd_rekey` (~1778). `get_pubkey` (~98) derives the pubkey from `key.txt`.
+- Tests run via `run "$SECRETS_BIN" <args>` with isolated `$HOME` and `$SECRETS_DIR`; helpers `init_with_remote`, `create_project_dir` live in `test/test_helper.bash`.
+
+---
+
+### Task 1: Recipient core (`RECIPIENTS_FILE`, validation, `_load_recipients`) wired into the push encrypt path
+
+**Files:**
+- Modify: `secrets` (constants ~line 19-21; `resolve_store` ~301; new helpers after `get_pubkey` ~99; encrypt sites ~655, ~684, ~1207, ~1357; `cmd_push` ~1268; `cmd_push_workspaces` ~1428; `push_dir_to_project`/`push_external_files` signatures)
+- Test: `test/recipients.bats` (new)
+
+**Interfaces:**
+- Produces: global `RECIPIENT_ARGS` (indexed array of `-r <key>` pairs); `RECIPIENTS_FILE` / `RECIPIENTS_FILE_NAME`; `_validate_age_recipient <str>` (0 = valid age1 key); `_load_recipients` (populates `RECIPIENT_ARGS`, dies on bad/symlinked/empty file).
+- Consumes: `get_pubkey`, `SECRETS_DIR`, `KEY_FILE`.
+
+- [ ] **Step 1: Write failing tests** in new `test/recipients.bats`:
+
+```bash
+#!/usr/bin/env bats
+load test_helper
+
+# A throwaway second identity for "another teammate".
+make_second_identity() {
+  age-keygen -o "$TEST_TMPDIR/bob.txt" 2>/dev/null
+  BOB_PUB=$(age-keygen -y "$TEST_TMPDIR/bob.txt")
+}
+
+@test "push without recipients.txt stays single-key (legacy behavior)" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+  # No recipients.txt was created by push.
+  [ ! -e "$SECRETS_DIR/recipients.txt" ]
+  # Blob decrypts with the store's own key.
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "push with a hand-written recipients.txt encrypts to every listed key" {
+  init_with_remote
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '# self\n%s\n# bob\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+  # Bob (a recipient) can decrypt the pushed blob with HIS key.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  [ "$status" -eq 0 ]
+  # And the store key still can too.
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "push refuses a recipients.txt with an invalid key" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\nnot-an-age-key\n' "$STORE_PUB" > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid recipient"* ]] || false
+}
+
+@test "push refuses a symlinked recipients.txt" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n' "$STORE_PUB" > "$TEST_TMPDIR/elsewhere.txt"
+  ln -s "$TEST_TMPDIR/elsewhere.txt" "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"symlink"* ]] || false
+}
+```
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `bats test/recipients.bats`
+Expected: FAIL (recipients.txt is ignored today; multi-recipient blob won't decrypt with bob's key; invalid/symlink cases don't error).
+
+- [ ] **Step 3: Add the constant + `RECIPIENTS_FILE` plumbing**
+
+Near `KEY_FILE="$SECRETS_DIR/key.txt"` (~line 20), add the name constant just above it and the path just below:
+
+```bash
+RECIPIENTS_FILE_NAME="recipients.txt"
+KEY_FILE="$SECRETS_DIR/key.txt"
+RECIPIENTS_FILE="$SECRETS_DIR/$RECIPIENTS_FILE_NAME"
+```
+
+Inside `resolve_store`, right after the line that re-sets `KEY_FILE="$SECRETS_DIR/key.txt"` (~line 301), add:
+
+```bash
+  RECIPIENTS_FILE="$SECRETS_DIR/$RECIPIENTS_FILE_NAME"
+```
+
+- [ ] **Step 4: Add `_validate_age_recipient` and `_load_recipients`** immediately after `get_pubkey` (~line 99):
+
+```bash
+# A native age X25519 recipient: "age1" + exactly 58 chars of [0-9a-z].
+# This is also the injection rail — it cannot hold shell metacharacters,
+# whitespace, control chars, or extra flags. SSH recipients are intentionally
+# unsupported (EGB-283 scope cut).
+_validate_age_recipient() {
+  case "$1" in
+    age1*) : ;;
+    *) return 1 ;;
+  esac
+  local body="${1#age1}"
+  [ "${#body}" -eq 58 ] || return 1
+  case "$body" in
+    *[!0-9a-z]*) return 1 ;;
+  esac
+  return 0
+}
+
+# Populate the global RECIPIENT_ARGS array with one "-r <key>" per store
+# recipient. recipients.txt present -> validated keys from the file (the store
+# is multi-recipient). Absent -> the single pubkey derived from key.txt (legacy
+# single-key store, exactly today's behavior). We parse the file ourselves
+# (never `age -R <path>`) because it is committed = an injection surface; every
+# line is validated and the file is refused if symlinked. Dies on any problem.
+RECIPIENT_ARGS=()
+_load_recipients() {
+  RECIPIENT_ARGS=()
+  if [ ! -e "$RECIPIENTS_FILE" ]; then
+    RECIPIENT_ARGS=(-r "$(get_pubkey)")
+    return 0
+  fi
+  if [ -L "$RECIPIENTS_FILE" ]; then
+    die "Refusing to read symlinked $RECIPIENTS_FILE_NAME (security)."
+  fi
+  local line trimmed n=0
+  while IFS= read -r line || [ -n "$line" ]; do
+    trimmed="${line#"${line%%[![:space:]]*}"}"     # lstrip
+    trimmed="${trimmed%"${trimmed##*[![:space:]]}"}" # rstrip
+    [ -z "$trimmed" ] && continue
+    case "$trimmed" in '#'*) continue ;; esac
+    if ! _validate_age_recipient "$trimmed"; then
+      die "Invalid recipient in $RECIPIENTS_FILE_NAME: '$trimmed' (expected a native age key: age1...)."
+    fi
+    RECIPIENT_ARGS+=(-r "$trimmed")
+    n=$((n + 1))
+  done < "$RECIPIENTS_FILE"
+  if [ "$n" -eq 0 ]; then
+    die "$RECIPIENTS_FILE_NAME has no recipients — a store must have at least one. Run 'secrets recipients add <age1...>'."
+  fi
+}
+```
+
+- [ ] **Step 5: Route every encrypt site through `RECIPIENT_ARGS`**
+
+In `push_dir_to_project`, change the encrypt line (~1207):
+```bash
+    age "${RECIPIENT_ARGS[@]}" -o "$SECRETS_DIR/$project/${name}.age" "$f"
+```
+and delete its now-unused `local pubkey="$3"` line (~1192).
+
+In `cmd_push`, change the inline encrypt (~1357):
+```bash
+    age "${RECIPIENT_ARGS[@]}" -o "$SECRETS_DIR/$project/${rel}.age" "$PWD/$rel"
+```
+
+In `push_external_files`, change both encrypt lines (~655 and ~684) to `age "${RECIPIENT_ARGS[@]}" -o …` (keep the rest of each line identical) and delete its `local pubkey="$3"` from the signature line `local root="$1" project="$2" pubkey="$3"` → `local root="$1" project="$2"`.
+
+- [ ] **Step 6: Load recipients in the push commands and drop the old `pubkey` threading**
+
+In `cmd_push` (~1268-1269) replace:
+```bash
+  local pubkey
+  pubkey=$(get_pubkey)
+```
+with:
+```bash
+  _load_recipients
+```
+and change the external call (~1365) `push_external_files "$PWD" "$project"` (drop `"$pubkey"`).
+
+In `cmd_push_workspaces` (~1428) replace the `pubkey=$(get_pubkey)` pair with `_load_recipients`, and drop the `"$pubkey"` argument from the `push_dir_to_project …` (~1432, ~1443) and `push_external_files …` (~1450) calls.
+
+- [ ] **Step 7: Run the tests**
+
+Run: `bats test/recipients.bats`
+Expected: PASS (4 tests).
+
+- [ ] **Step 8: Run the full suite to confirm no regression**
+
+Run: `bats test/`
+Expected: PASS (all existing tests still green — legacy push/pull unchanged).
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add secrets test/recipients.bats
+git commit -m "feat: multi-recipient encrypt core + recipients.txt (EGB-283)"
+```
+
+---
+
+### Task 2: `secrets recipients list`
+
+**Files:**
+- Modify: `secrets` (new `_recipients_dump`, `cmd_recipients`, `_recipients_list`; dispatch + nothing in help yet)
+- Test: `test/recipients.bats`
+
+**Interfaces:**
+- Produces: `_recipients_dump` (emits `<key>\t<name>` per recipient, name = nearest preceding `# <name>` comment or empty); `cmd_recipients <sub> …` (routes `list`); `_recipients_list`.
+- Consumes: `_load_recipients`, `RECIPIENTS_FILE`, `get_pubkey`.
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+@test "recipients list on a legacy store shows the single derived key" {
+  init_with_remote
+  run "$SECRETS_BIN" recipients list
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"single-key"* ]] || false
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  [[ "$output" == *"$STORE_PUB"* ]] || false
+}
+
+@test "recipients list shows names and keys from recipients.txt" {
+  init_with_remote
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '# alice\n%s\n# bob\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  run "$SECRETS_BIN" recipients list
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"recipients: 2"* ]] || false
+  [[ "$output" == *"alice"* ]] || false
+  [[ "$output" == *"bob"* ]] || false
+}
+```
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `bats test/recipients.bats -f "recipients list"`
+Expected: FAIL ("Unknown command: recipients").
+
+- [ ] **Step 3: Add `_recipients_dump`** (place after `_load_recipients`):
+
+```bash
+# Emit "<key>\t<name>" for each recipient in recipients.txt. <name> is the most
+# recent preceding "# <name>" comment, or empty. Read-only; no validation
+# (callers that need rails call _load_recipients separately).
+_recipients_dump() {
+  [ -e "$RECIPIENTS_FILE" ] || return 0
+  local line trimmed name=""
+  while IFS= read -r line || [ -n "$line" ]; do
+    trimmed="${line#"${line%%[![:space:]]*}"}"
+    trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
+    [ -z "$trimmed" ] && continue
+    case "$trimmed" in
+      '#'*)
+        name="${trimmed#\#}"
+        name="${name#"${name%%[![:space:]]*}"}"
+        ;;
+      *)
+        printf '%s\t%s\n' "$trimmed" "$name"
+        name=""
+        ;;
+    esac
+  done < "$RECIPIENTS_FILE"
+}
+```
+
+- [ ] **Step 4: Add `cmd_recipients` + `_recipients_list`** (place near `cmd_which`):
+
+```bash
+cmd_recipients() {
+  resolve_store
+  local sub="${1:-list}"
+  [ $# -gt 0 ] && shift
+  case "$sub" in
+    list) _recipients_list ;;
+    *) die "Unknown recipients subcommand: '$sub'. Usage: secrets recipients [list]" ;;
+  esac
+}
+
+_recipients_list() {
+  check_initialized
+  if [ ! -e "$RECIPIENTS_FILE" ]; then
+    check_key
+    echo "recipients: single-key (no $RECIPIENTS_FILE_NAME)"
+    echo "  $(get_pubkey)"
+    return 0
+  fi
+  _load_recipients   # validates the file (dies on bad key / symlink)
+  local count=0 k n
+  while IFS=$'\t' read -r k n; do count=$((count + 1)); done < <(_recipients_dump)
+  echo "recipients: $count (from $RECIPIENTS_FILE_NAME)"
+  while IFS=$'\t' read -r k n; do
+    if [ -n "$n" ]; then echo "  $k  ($n)"; else echo "  $k"; fi
+  done < <(_recipients_dump)
+}
+```
+
+- [ ] **Step 5: Wire dispatch.** In the `case "${1:-help}"` block, add above `which|where|status`:
+```bash
+  recipients) shift; cmd_recipients "$@" ;;
+```
+
+- [ ] **Step 6: Run the tests**
+
+Run: `bats test/recipients.bats -f "recipients list"`
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add secrets test/recipients.bats
+git commit -m "feat: secrets recipients list (EGB-283)"
+```
+
+---
+
+### Task 3: Shared `_reencrypt_all` engine + `secrets reencrypt` + dual `rekey`
+
+**Files:**
+- Modify: `secrets` (new `_reencrypt_all`, `cmd_reencrypt`; rewrite `cmd_rekey` head to branch; dispatch)
+- Test: `test/recipients.bats`
+
+**Interfaces:**
+- Produces: `_reencrypt_all <commit-msg>` (decrypt whole store with `KEY_FILE`, re-encrypt to `RECIPIENT_ARGS`, commit + push; aborts with store intact on decrypt failure; no-op on empty store); `cmd_reencrypt`.
+- Consumes: `_load_recipients`, `RECIPIENT_ARGS`, `KEY_FILE`, `ensure_store_protections`.
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+@test "reencrypt re-encrypts existing blobs to a newly added recipient line" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push           # single-key blob
+  [ "$status" -eq 0 ]
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  # Bob cannot read the old single-key blob yet.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  [ "$status" -ne 0 ]
+  run "$SECRETS_BIN" reencrypt
+  [ "$status" -eq 0 ]
+  # Now he can.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "rekey on a multi-recipient store keeps recipients and the same key" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  before=$(cat "$SECRETS_DIR/key.txt")
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  run "$SECRETS_BIN" rekey
+  [ "$status" -eq 0 ]
+  # No new keypair was generated.
+  [ "$(cat "$SECRETS_DIR/key.txt")" = "$before" ]
+  # Both recipients can decrypt.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "rekey on a legacy store still rotates to a new key (unchanged)" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  before=$(cat "$SECRETS_DIR/key.txt")
+  run "$SECRETS_BIN" rekey
+  [ "$status" -eq 0 ]
+  [ "$(cat "$SECRETS_DIR/key.txt")" != "$before" ]
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+```
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `bats test/recipients.bats -f "reencrypt|rekey on"`
+Expected: FAIL ("Unknown command: reencrypt"; multi rekey generates a new key today).
+
+- [ ] **Step 3: Add `_reencrypt_all`** (place just before `cmd_rekey`):
+
+```bash
+# Decrypt every blob in the store with the local key and re-encrypt each to the
+# currently-loaded RECIPIENT_ARGS, then commit + push. The caller MUST have run
+# _load_recipients (or set RECIPIENT_ARGS) and check_key first. Aborts with the
+# store untouched on any decrypt failure (you must be a current recipient).
+# Shared by recipients add/rm, reencrypt, and multi-recipient rekey.
+_reencrypt_all() {
+  local commit_msg="$1"
+  local tmpdir
+  tmpdir=$(mktemp -d)
+  trap 'rm -rf "${tmpdir:-}"' EXIT INT TERM
+
+  info "Decrypting all blobs with your key..."
+  local file_count=0 dir project f rel dest
+  for dir in "$SECRETS_DIR"/*/; do
+    [ -d "$dir" ] || continue
+    project=$(basename "$dir")
+    case "$project" in .*) continue ;; esac
+    mkdir -p "$tmpdir/$project"
+    while IFS= read -r f; do
+      [ -f "$f" ] || continue
+      rel=${f#"$dir"}; rel=${rel%.age}
+      dest="$tmpdir/$project/$rel"
+      mkdir -p "$(dirname "$dest")"
+      if ! age -d -i "$KEY_FILE" -o "$dest" "$f"; then
+        die "Decryption failed for $project/$rel (are you a current recipient?). Aborted; store unchanged."
+      fi
+      file_count=$((file_count + 1))
+    done < <(find "$dir" -type f -name '*.age')
+  done
+
+  if [ "$file_count" -eq 0 ]; then
+    rm -rf "$tmpdir"; trap - EXIT INT TERM
+    info "No encrypted blobs in the store — nothing to re-encrypt."
+    return 0
+  fi
+
+  local rc=$(( ${#RECIPIENT_ARGS[@]} / 2 ))
+  info "Re-encrypting $file_count blob(s) to $rc recipient(s)..."
+  for dir in "$tmpdir"/*/; do
+    [ -d "$dir" ] || continue
+    project=$(basename "$dir")
+    mkdir -p "$SECRETS_DIR/$project"
+    while IFS= read -r f; do
+      [ -f "$f" ] || continue
+      rel=${f#"$dir"}
+      mkdir -p "$(dirname "$SECRETS_DIR/$project/$rel")"
+      age "${RECIPIENT_ARGS[@]}" -o "$SECRETS_DIR/$project/${rel}.age" "$f"
+    done < <(find "$dir" -type f)
+  done
+
+  ensure_store_protections
+  git -C "$SECRETS_DIR" add -A
+  git -C "$SECRETS_DIR" commit -m "$commit_msg" >/dev/null
+  if git -C "$SECRETS_DIR" remote get-url origin >/dev/null 2>&1; then
+    git -C "$SECRETS_DIR" push >/dev/null 2>&1
+    info "Pushed re-encrypted secrets to remote"
+  else
+    info "Committed re-encrypted secrets locally (no remote configured)"
+  fi
+  rm -rf "$tmpdir"; trap - EXIT INT TERM
+}
+
+cmd_reencrypt() {
+  check_cmd age
+  check_cmd git
+  resolve_store
+  check_initialized
+  check_key
+  _load_recipients
+  _reencrypt_all "reencrypt: re-encrypt all to current recipients"
+}
+```
+
+- [ ] **Step 4: Branch `cmd_rekey`.** Replace the head of `cmd_rekey` — from its `check_cmd age` line down to and including the `info "Decrypting all files with current key..."` line — with the block below. **Leave the rest of the existing legacy body (temp dir, decrypt loop, keygen, re-encrypt loop, commit/push) exactly as-is** below this insertion:
+
+```bash
+cmd_rekey() {
+  check_cmd age
+  check_cmd git
+  resolve_store
+  check_initialized
+  check_key
+
+  # EGB-283: on a multi-recipient store, rekey means "re-encrypt every blob to
+  # the current recipients.txt set" — NOT a new keypair (rotating an identity is
+  # the member's own age-keygen + recipients rm/add). Legacy stores (no
+  # recipients.txt) keep the original generate-new-keypair behavior below.
+  if [ -e "$RECIPIENTS_FILE" ]; then
+    _load_recipients
+    info "Multi-recipient store — re-encrypting to $RECIPIENTS_FILE_NAME (no new key generated)."
+    _reencrypt_all "rekey: re-encrypt all to current recipients"
+    return 0
+  fi
+
+  # ── Legacy single-key rotation (unchanged) ──
+  info "Decrypting all files with current key..."
+```
+
+- [ ] **Step 5: Wire dispatch.** Add near `rekey)`:
+```bash
+  reencrypt) cmd_reencrypt ;;
+```
+
+- [ ] **Step 6: Run the tests**
+
+Run: `bats test/recipients.bats -f "reencrypt|rekey"`
+Expected: PASS (3 tests).
+
+- [ ] **Step 7: Run the full suite** (the legacy rekey tests in `secrets.bats` must still pass)
+
+Run: `bats test/`
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add secrets test/recipients.bats
+git commit -m "feat: shared _reencrypt_all + reencrypt cmd + dual rekey (EGB-283)"
+```
+
+---
+
+### Task 4: `secrets recipients add`
+
+**Files:**
+- Modify: `secrets` (`_recipients_add`, `_validate_recipient_name`; extend `cmd_recipients` case)
+- Test: `test/recipients.bats`
+
+**Interfaces:**
+- Produces: `_recipients_add <age1…> [--name <label>]` (validate, bootstrap legacy store with self key, reject dup, append, re-encrypt all); `_validate_recipient_name`.
+- Consumes: `_recipients_dump`, `_load_recipients`, `_reencrypt_all`, `get_pubkey`, `_validate_age_recipient`.
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+@test "recipients add bootstraps a legacy store and re-encrypts" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  [ "$status" -eq 0 ]
+  [ -e "$SECRETS_DIR/recipients.txt" ]
+  # recipients.txt now has self + bob (2 keys).
+  run "$SECRETS_BIN" recipients list
+  [[ "$output" == *"recipients: 2"* ]] || false
+  [[ "$output" == *"bob"* ]] || false
+  # Existing blob re-encrypted: bob can read it.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "recipients add rejects a non-age key" {
+  init_with_remote
+  run "$SECRETS_BIN" recipients add "ssh-ed25519 AAAAfoo"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"valid age recipient"* ]] || false
+}
+
+@test "recipients add rejects a duplicate" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  [ "$status" -eq 0 ]
+  run "$SECRETS_BIN" recipients add "$BOB_PUB"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"already present"* ]] || false
+}
+
+@test "recipients add rejects an unsafe --name" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name 'bob; rm -rf ~'
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid --name"* ]] || false
+}
+```
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `bats test/recipients.bats -f "recipients add"`
+Expected: FAIL ("Unknown recipients subcommand: 'add'").
+
+- [ ] **Step 3: Add `_validate_recipient_name`** (place near `_validate_age_recipient`):
+
+```bash
+# Recipient display names become "# <name>" comment lines in recipients.txt.
+# Restrict to a safe charset so a name can't inject extra lines/metacharacters.
+_validate_recipient_name() {
+  case "$1" in
+    *[!A-Za-z0-9\ ._-]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+```
+
+- [ ] **Step 4: Add `_recipients_add`** (place after `_recipients_list`):
+
+```bash
+_recipients_add() {
+  check_cmd age
+  check_cmd git
+  check_initialized
+  check_key
+  local key="" name=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --name) name="${2:-}"; shift 2 ;;
+      -*) die "Unknown flag: $1. Usage: secrets recipients add <age1...> [--name <label>]" ;;
+      *) if [ -z "$key" ]; then key="$1"; else die "Unexpected argument: $1"; fi; shift ;;
+    esac
+  done
+  [ -n "$key" ] || die "Usage: secrets recipients add <age1...> [--name <label>]"
+  _validate_age_recipient "$key" || die "Not a valid age recipient: '$key' (expected age1..., 62 chars; SSH keys unsupported)."
+  if [ -n "$name" ]; then
+    _validate_recipient_name "$name" || die "Invalid --name '$name' (allowed: letters, digits, space, . _ -)."
+  fi
+  if [ -L "$RECIPIENTS_FILE" ]; then
+    die "Refusing to write symlinked $RECIPIENTS_FILE_NAME."
+  fi
+  # Bootstrap a legacy store: seed this machine's key first so the operator
+  # stays a recipient (and can decrypt to re-encrypt).
+  if [ ! -e "$RECIPIENTS_FILE" ]; then
+    printf '# self\n%s\n' "$(get_pubkey)" > "$RECIPIENTS_FILE"
+  fi
+  local k _n
+  while IFS=$'\t' read -r k _n; do
+    [ "$k" = "$key" ] && die "Recipient already present: $key"
+  done < <(_recipients_dump)
+  { [ -n "$name" ] && printf '# %s\n' "$name"; printf '%s\n' "$key"; } >> "$RECIPIENTS_FILE"
+  info "Added recipient${name:+ ($name)}: $key"
+  _load_recipients
+  _reencrypt_all "recipients: add ${name:-$key}; re-encrypt all"
+}
+```
+
+- [ ] **Step 5: Extend `cmd_recipients`** — add the `add)` arm:
+
+```bash
+    list) _recipients_list ;;
+    add)  _recipients_add "$@" ;;
+    *) die "Unknown recipients subcommand: '$sub'. Usage: secrets recipients [list|add <age1...> [--name N]]" ;;
+```
+
+- [ ] **Step 6: Run the tests**
+
+Run: `bats test/recipients.bats -f "recipients add"`
+Expected: PASS (4 tests).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add secrets test/recipients.bats
+git commit -m "feat: secrets recipients add (EGB-283)"
+```
+
+---
+
+### Task 5: `secrets recipients rm` with last-recipient and self-lockout guards
+
+**Files:**
+- Modify: `secrets` (`_recipients_rm`, `_recipients_write_without`; extend `cmd_recipients` case)
+- Test: `test/recipients.bats`
+
+**Interfaces:**
+- Produces: `_recipients_rm <age1…|name> [--yes]`; `_recipients_write_without <key>` (canonical rewrite dropping one key + its name comment).
+- Consumes: `_recipients_dump`, `_load_recipients`, `_reencrypt_all`, `get_pubkey`.
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+@test "recipients rm removes a recipient and re-encrypts to the rest" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  run "$SECRETS_BIN" recipients rm bob
+  [ "$status" -eq 0 ]
+  run "$SECRETS_BIN" recipients list
+  [[ "$output" == *"recipients: 1"* ]] || false
+  # Store key still reads its own blobs.
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "recipients rm refuses to remove the last recipient" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob   # store = self + bob
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  run "$SECRETS_BIN" recipients rm bob                       # back to self only
+  [ "$status" -eq 0 ]
+  run "$SECRETS_BIN" recipients rm "$STORE_PUB"              # would be the last
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"last recipient"* ]] || false
+}
+
+@test "recipients rm of your own key requires --yes" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  run "$SECRETS_BIN" recipients rm "$STORE_PUB"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"your own key"* ]] || false
+  run "$SECRETS_BIN" recipients rm "$STORE_PUB" --yes
+  [ "$status" -eq 0 ]
+}
+
+@test "recipients rm of a non-existent target errors" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  run "$SECRETS_BIN" recipients rm carol
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"No recipient matches"* ]] || false
+}
+```
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `bats test/recipients.bats -f "recipients rm"`
+Expected: FAIL ("Unknown recipients subcommand: 'rm'").
+
+- [ ] **Step 3: Add `_recipients_write_without` + `_recipients_rm`** (after `_recipients_add`):
+
+```bash
+# Rewrite recipients.txt canonically (one "# name"? + key per entry), dropping
+# the entry whose key == <drop>. Atomic-ish via temp file in the same dir.
+_recipients_write_without() {
+  local drop="$1" tmp k n
+  tmp=$(mktemp "$SECRETS_DIR/.recipients.XXXXXX")
+  while IFS=$'\t' read -r k n; do
+    [ "$k" = "$drop" ] && continue
+    [ -n "$n" ] && printf '# %s\n' "$n" >> "$tmp"
+    printf '%s\n' "$k" >> "$tmp"
+  done < <(_recipients_dump)
+  mv "$tmp" "$RECIPIENTS_FILE"
+}
+
+_recipients_rm() {
+  check_cmd age
+  check_cmd git
+  check_initialized
+  check_key
+  local target="" assume_yes=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --yes|-y) assume_yes=true; shift ;;
+      -*) die "Unknown flag: $1. Usage: secrets recipients rm <age1...|name> [--yes]" ;;
+      *) if [ -z "$target" ]; then target="$1"; else die "Unexpected argument: $1"; fi; shift ;;
+    esac
+  done
+  [ -n "$target" ] || die "Usage: secrets recipients rm <age1...|name> [--yes]"
+  [ -e "$RECIPIENTS_FILE" ] || die "No $RECIPIENTS_FILE_NAME — store is single-key; nothing to remove."
+  [ -L "$RECIPIENTS_FILE" ] && die "Refusing to write symlinked $RECIPIENTS_FILE_NAME."
+  local k n match="" count=0 total=0
+  while IFS=$'\t' read -r k n; do
+    total=$((total + 1))
+    if [ "$k" = "$target" ] || { [ -n "$n" ] && [ "$n" = "$target" ]; }; then
+      match="$k"; count=$((count + 1))
+    fi
+  done < <(_recipients_dump)
+  [ "$count" -eq 0 ] && die "No recipient matches '$target'."
+  [ "$count" -gt 1 ] && die "'$target' matches $count recipients by name — remove by key (age1...) instead."
+  [ "$total" -le 1 ] && die "Refusing to remove the last recipient — a store must have at least one."
+  local self; self="$(get_pubkey)"
+  if [ "$match" = "$self" ] && [ "$assume_yes" != true ]; then
+    die "Refusing to remove your own key (you would lose access to future pushes). Re-run with --yes to confirm."
+  fi
+  _recipients_write_without "$match"
+  info "Removed recipient: $match"
+  _load_recipients
+  _reencrypt_all "recipients: remove $match; re-encrypt all"
+}
+```
+
+- [ ] **Step 4: Extend `cmd_recipients`** — add the `rm)`/`remove)` arm:
+
+```bash
+    list) _recipients_list ;;
+    add)  _recipients_add "$@" ;;
+    rm|remove) _recipients_rm "$@" ;;
+    *) die "Unknown recipients subcommand: '$sub'. Usage: secrets recipients [list|add <age1...> [--name N]|rm <age1...|name> [--yes]]" ;;
+```
+
+- [ ] **Step 5: Run the tests**
+
+Run: `bats test/recipients.bats -f "recipients rm"`
+Expected: PASS (4 tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add secrets test/recipients.bats
+git commit -m "feat: secrets recipients rm with lockout guards (EGB-283)"
+```
+
+---
+
+### Task 6: `init` born-multi seeding + `which` recipients line
+
+**Files:**
+- Modify: `secrets` (`cmd_init` ~1176; `cmd_which` ~1913)
+- Test: `test/recipients.bats`
+
+**Interfaces:**
+- Consumes: `RECIPIENTS_FILE`, `get_pubkey`, `_recipients_dump`.
+- Produces: a `recipients.txt` seeded at `init`; a `recipients:` line in `which` output.
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+@test "init seeds recipients.txt with the new store key (born-multi)" {
+  run "$SECRETS_BIN" init
+  [ "$status" -eq 0 ]
+  [ -e "$SECRETS_DIR/recipients.txt" ]
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  run cat "$SECRETS_DIR/recipients.txt"
+  [[ "$output" == *"$STORE_PUB"* ]] || false
+}
+
+@test "which reports the recipient count" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  create_project_dir myproj
+  run "$SECRETS_BIN" which
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"recipients: 2"* ]] || false
+  [[ "$output" == *"bob"* ]] || false
+}
+```
+
+Note: the first test will change `init`'s observable output — confirm no existing `secrets.bats` test asserts the *absence* of `recipients.txt` after `init`. If one does, update it in this task.
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `bats test/recipients.bats -f "born-multi|which reports"`
+Expected: FAIL.
+
+- [ ] **Step 3: Seed in `cmd_init`.** After `pubkey=$(get_pubkey)` (~1176) and before the `info "Done!..."` banner, add:
+
+```bash
+  # EGB-283: born-multi — seed recipients.txt with this store's public key so
+  # the store is multi-recipient-ready from day one. Committed (not gitignored),
+  # staged by the first push like .secrets-format.
+  printf '# self\n%s\n' "$pubkey" > "$RECIPIENTS_FILE"
+```
+
+- [ ] **Step 4: Add the `which` line.** In `cmd_which`, right after `echo "format: v$(_store_format)"` (~1913), add:
+
+```bash
+  # EGB-283: surface the recipient set (store-scoped; one key per team member).
+  if [ -e "$RECIPIENTS_FILE" ] && [ ! -L "$RECIPIENTS_FILE" ]; then
+    local rcount=0 rk rn rnames=""
+    while IFS=$'\t' read -r rk rn; do
+      rcount=$((rcount + 1))
+      [ -n "$rn" ] && rnames="${rnames:+$rnames, }$rn"
+    done < <(_recipients_dump)
+    if [ -n "$rnames" ]; then
+      echo "recipients: $rcount ($rnames)"
+    else
+      echo "recipients: $rcount"
+    fi
+  else
+    echo "recipients: single-key (no $RECIPIENTS_FILE_NAME)"
+  fi
+```
+
+- [ ] **Step 5: Run the tests + full suite**
+
+Run: `bats test/recipients.bats -f "born-multi|which reports"` then `bats test/`
+Expected: PASS. (If a legacy `secrets.bats`/`migrate.bats` test broke on the new `init` output or the new `which` line, fix that test to expect the new line and re-run.)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add secrets test/
+git commit -m "feat: init born-multi recipients.txt + which recipients line (EGB-283)"
+```
+
+---
+
+### Task 7: `verify` recipient-count invariant
+
+**Files:**
+- Modify: `secrets` (`_blob_recipient_count`, `_check_blob_recipient_count`; `_verify_project` ~2017; `_verify_all` ~1970)
+- Test: `test/recipients.bats`
+
+**Interfaces:**
+- Produces: `_blob_recipient_count <blob>` (count of `-> ` stanzas in the age header); `_check_blob_recipient_count <blob> <rel> <expected>` (echoes a FINDING + returns 1 on mismatch, 0 if expected empty/legacy).
+- Consumes: `_load_recipients`, `RECIPIENT_ARGS`, `RECIPIENTS_FILE`.
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+@test "verify --all passes on a healthy multi-recipient store" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob   # re-encrypts to 2
+  run "$SECRETS_BIN" verify --all
+  [ "$status" -eq 0 ]
+}
+
+@test "verify flags a blob whose recipient count drifted" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push                                   # single-key blob (1 stanza)
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  # Declare 2 recipients but do NOT re-encrypt — the on-disk blob still has 1.
+  printf '%s\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  run "$SECRETS_BIN" verify --all
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"recipient"* ]] || false
+}
+```
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `bats test/recipients.bats -f "verify"`
+Expected: the drift test FAILs (verify is green today even with a stale blob).
+
+- [ ] **Step 3: Add the helpers** (place near `_verify_blob_decrypts` ~1961):
+
+```bash
+# Count age recipient stanzas ("-> ...") in a blob's header. The age v1 header
+# is ASCII and ends at the "--- <mac>" line, so reading line-by-line stops
+# before any binary body. Echoes the count.
+_blob_recipient_count() {
+  local f="$1" line count=0
+  while IFS= read -r line; do
+    case "$line" in
+      '--- '*) break ;;
+      '-> '*) count=$((count + 1)) ;;
+    esac
+  done < "$f"
+  echo "$count"
+}
+
+# If the store is multi-recipient (expected non-empty), assert <blob> was
+# encrypted to exactly <expected> recipients. Echoes a FINDING and returns 1 on
+# mismatch; returns 0 otherwise (incl. legacy stores where expected is empty).
+_check_blob_recipient_count() {
+  local blob="$1" rel="$2" expected="$3"
+  [ -n "$expected" ] || return 0
+  local actual; actual=$(_blob_recipient_count "$blob")
+  if [ "$actual" != "$expected" ]; then
+    echo "FINDING: $rel is encrypted to $actual recipient(s) but $RECIPIENTS_FILE_NAME has $expected — run 'secrets reencrypt'." >&2
+    return 1
+  fi
+  return 0
+}
+```
+
+- [ ] **Step 4: Compute the expected count + check in `_verify_all`.** Near the top of `_verify_all` (after `local checked=0 failed=0 …`), add:
+
+```bash
+  local rexpected=""
+  if [ -e "$RECIPIENTS_FILE" ] && [ ! -L "$RECIPIENTS_FILE" ]; then
+    _load_recipients   # validates; dies on a bad recipients.txt
+    rexpected=$(( ${#RECIPIENT_ARGS[@]} / 2 ))
+  fi
+```
+
+Then, inside its blob loop, right after the `_verify_blob_decrypts` block, add:
+
+```bash
+      if ! _check_blob_recipient_count "$f" "${f#"$SECRETS_DIR"/}" "$rexpected"; then
+        failed=$((failed + 1))
+      fi
+```
+
+- [ ] **Step 5: Same in `_verify_project`.** After its `local findings=0 checked=0` add the same `rexpected` block. Then after EACH of the two `_verify_blob_decrypts` checks (the dotenv `blob` loop and the external `eblob` loop), add a count check that increments `findings`:
+
+```bash
+    # dotenv loop, after the decrypt check:
+    if ! _check_blob_recipient_count "$blob" "$project/$rel.age" "$rexpected"; then
+      findings=$((findings + 1))
+    fi
+```
+```bash
+    # external loop, after the decrypt check:
+    if ! _check_blob_recipient_count "$eblob" "$project/$erel" "$rexpected"; then
+      findings=$((findings + 1))
+    fi
+```
+
+- [ ] **Step 6: Run the tests + full suite**
+
+Run: `bats test/recipients.bats -f "verify"` then `bats test/`
+Expected: PASS. (`_verify_project` tests in other suites run against single-key stores where `rexpected` is empty → checks are skipped, so they stay green.)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add secrets test/recipients.bats
+git commit -m "feat: verify asserts blob recipient-count matches recipients.txt (EGB-283)"
+```
+
+---
+
+### Task 8: Security regression fixtures for `recipients.txt`
+
+**Files:**
+- Modify: `test/recipients.bats` (adversarial fixtures only — no `secrets` changes expected; if a case slips through, fix the rail in `secrets` here)
+
+**Interfaces:** none new — exercises `_load_recipients` / `_recipients_add` rails via the CLI.
+
+> Policy reminder: these are ordinary defensive regression tests. Do NOT dispatch red-team/adversarial-review subagents and do NOT run `./test/run-security.sh` — that is operator-local.
+
+- [ ] **Step 1: Write the fixtures**
+
+```bash
+@test "SECURITY: recipients.txt with shell metacharacters is rejected, no execution" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\nage1$(touch %s/pwned)\n' "$STORE_PUB" "$TEST_TMPDIR" > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [ ! -e "$TEST_TMPDIR/pwned" ]
+  [[ "$output" == *"Invalid recipient"* ]] || false
+}
+
+@test "SECURITY: recipients.txt line that looks like an extra age flag is rejected" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n-i /etc/passwd\n' "$STORE_PUB" > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid recipient"* ]] || false
+}
+
+@test "SECURITY: control/ANSI characters in recipients.txt are rejected" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\nage1%b\n' "$STORE_PUB" 'aaaa\033[31mevil' > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+}
+
+@test "SECURITY: recipients add rejects a key with embedded whitespace" {
+  init_with_remote
+  run "$SECRETS_BIN" recipients add "age1aaaa bbbb"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"valid age recipient"* ]] || false
+}
+
+@test "SECURITY: a symlinked recipients.txt is refused on add and rm too" {
+  init_with_remote
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n' "$STORE_PUB" > "$TEST_TMPDIR/elsewhere.txt"
+  ln -s "$TEST_TMPDIR/elsewhere.txt" "$SECRETS_DIR/recipients.txt"
+  run "$SECRETS_BIN" recipients add "$BOB_PUB"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"symlink"* ]] || false
+}
+```
+
+- [ ] **Step 2: Run them**
+
+Run: `bats test/recipients.bats -f "SECURITY"`
+Expected: PASS. If any FAILS, the corresponding rail in `secrets` (`_validate_age_recipient`, the `-L` symlink guard in `_load_recipients`/`_recipients_add`/`_recipients_rm`) is too loose — tighten it, then re-run.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add test/recipients.bats
+git commit -m "test: recipients.txt security regression fixtures (EGB-283)"
+```
+
+---
+
+### Task 9: Docs, help text, version bump
+
+**Files:**
+- Modify: `secrets` (`cmd_help`); `CLAUDE.md`; `README.md`; `VERSION`/version constant if one exists
+
+**Interfaces:** none.
+
+- [ ] **Step 1: Add help text.** In `cmd_help`, in the command list, add lines (match the existing column style):
+
+```
+  secrets recipients list           List the store's recipient keys
+  secrets recipients add KEY [--name N]  Add a recipient and re-encrypt the store
+  secrets recipients rm KEY|NAME [--yes] Remove a recipient and re-encrypt the store
+  secrets reencrypt                 Re-encrypt every blob to the current recipients
+```
+
+- [ ] **Step 2: Update `CLAUDE.md`.** In the Architecture section add a multi-recipient bullet:
+
+```
+- Multi-recipient (EGB-283): a store-scoped, committed `recipients.txt` (age `-R`
+  format, `# name` comments) lets one store encrypt every blob to N age keys —
+  one per team member. Managed via `secrets recipients add/rm/list`; absence of
+  the file ⇒ legacy single-key behavior (recipients = the pubkey derived from
+  `key.txt`). The file is parsed by us (never `age -R <path>`) into a validated
+  `RECIPIENT_ARGS` array (native age X25519 only, `age1[0-9a-z]{58}`; SSH
+  recipients rejected; symlinked file refused) — same conservative posture as
+  `.secrets-store`/`.secrets-files`. `_load_recipients` populates the array;
+  every encrypt site routes through it. Any recipient change re-encrypts the
+  WHOLE store in one commit via the shared `_reencrypt_all` engine (also used by
+  the new `secrets reencrypt` and by `rekey` on a multi-recipient store, where
+  rekey re-encrypts to the set with NO new keypair; legacy stores keep rekey's
+  generate-new-keypair behavior). `init` seeds `recipients.txt` born-multi.
+  `which` prints `recipients: N`; `verify`/`verify --all` assert each blob's
+  age recipient-stanza count equals `recipients.txt`'s length. Removal takes
+  effect going forward — git history stays readable by an old key, so rotate
+  genuinely-sensitive values. Decryption is unchanged (each member uses their
+  own `key.txt`).
+```
+
+Also update the subcommand list line (`init, push, pull, list, rm, rekey, verify, migrate`) to include `recipients, reencrypt`, and bump the `secrets.bats`/suite test counts and `bats test/` description in Project Structure (recipients.bats is the 4th suite).
+
+- [ ] **Step 3: Update `README.md`** — add an onboarding/offboarding section: a teammate runs `age-keygen`, sends their public key; an existing member runs `secrets recipients add age1… --name them` (store re-encrypts + pushes); the teammate clones the store, drops their own `key.txt`, and `secrets pull` works. Offboarding: `secrets recipients rm them` (+ rotate still-sensitive values, since history stays readable by the old key). Document `recipients list` and `reencrypt`.
+
+- [ ] **Step 4: Version bump.** If the repo carries a version constant/`VERSION` (recent commits bumped `0.6.1.0`), bump it (e.g. `0.6.2.0`) and add a CHANGELOG entry per the repo's convention.
+
+- [ ] **Step 5: Run the full suite once more**
+
+Run: `bats test/`
+Expected: PASS (all four suites).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add secrets CLAUDE.md README.md
+git commit -m "docs: multi-recipient age encryption (recipients/reencrypt) + version bump (EGB-283)"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- recipients.txt format + rails → Tasks 1, 8. ✓
+- `_load_recipients` / `RECIPIENT_ARGS` at every encrypt site → Task 1. ✓
+- `_reencrypt_all` shared engine + add/rm/rekey/reencrypt routing → Tasks 3, 4, 5. ✓
+- `recipients list/add/rm` with guards (last, self/--yes) → Tasks 2, 4, 5. ✓
+- Backward compat (absence = legacy; bootstrap on first add) → Tasks 1, 4. ✓
+- `init` born-multi → Task 6. ✓
+- `rekey` dual semantics → Task 3. ✓
+- `which` recipients line → Task 6. ✓
+- `verify` stanza-count invariant → Task 7. ✓
+- Security regression fixtures + policy note → Task 8. ✓
+- Docs/help/version → Task 9. ✓
+- Scope cuts (SSH, per-file subsets, key discovery) → enforced by `_validate_age_recipient` (rejects SSH) and simply not built. ✓
+
+**Placeholder scan:** every code/test step carries real bash/bats. No TBD/TODO. ✓
+
+**Type/name consistency:** `RECIPIENT_ARGS`, `RECIPIENTS_FILE`, `RECIPIENTS_FILE_NAME`, `_load_recipients`, `_validate_age_recipient`, `_validate_recipient_name`, `_recipients_dump`, `_recipients_list`, `_recipients_add`, `_recipients_rm`, `_recipients_write_without`, `_reencrypt_all`, `cmd_reencrypt`, `cmd_recipients`, `_blob_recipient_count`, `_check_blob_recipient_count` — used consistently across tasks. ✓
+
+**Known caveat to verify during execution:** Task 6 changes `init` output (now writes `recipients.txt`) and adds a `which` line; if any existing test in `secrets.bats`/`migrate.bats` asserts on exact `init`/`which` output or the absence of store files, update it in Task 6 (called out in that task's steps).

From 0f9de1c2fd5a716eff5ebd3e9f628963d8bbf8b7 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 12:33:05 -0700
Subject: [PATCH 03/20] feat: multi-recipient encrypt core + recipients.txt
 (EGB-283)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add RECIPIENTS_FILE_NAME / RECIPIENTS_FILE constants; update resolve_store to re-derive RECIPIENTS_FILE after store resolution.
- Add _validate_age_recipient (native age1 X25519 key format check, injection rail).
- Add RECIPIENT_ARGS global array and _load_recipients (absent → single pubkey legacy path; present → parse+validate recipients.txt, refuse symlink, die on bad/empty).
- Rewire all 5 push encrypt sites (push_dir_to_project, cmd_push inline, push_external_files ×2, cmd_push_workspaces) to use RECIPIENT_ARGS; drop pubkey threading from push_dir_to_project and push_external_files signatures.
- New test/recipients.bats (4 tests): legacy single-key, multi-recipient decrypt, invalid key rejection, symlink rejection.
- Fix test/test_helper.bash: set GIT_AUTHOR/COMMITTER env vars so git commit works with isolated $HOME.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 secrets               | 78 +++++++++++++++++++++++++++++++++++--------
 test/recipients.bats  | 57 +++++++++++++++++++++++++++++++
 test/test_helper.bash |  8 +++++
 3 files changed, 129 insertions(+), 14 deletions(-)
 create mode 100644 test/recipients.bats

diff --git a/secrets b/secrets
index 02a3415..a2f5209 100755
--- a/secrets
+++ b/secrets
@@ -17,7 +17,9 @@ set -euo pipefail
 # while letting .secrets-store files take precedence per project.
 _USER_SECRETS_DIR="${SECRETS_DIR:-}"
 SECRETS_DIR="${SECRETS_DIR:-$HOME/.secrets}"
+RECIPIENTS_FILE_NAME="recipients.txt"
 KEY_FILE="$SECRETS_DIR/key.txt"
+RECIPIENTS_FILE="$SECRETS_DIR/$RECIPIENTS_FILE_NAME"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Set by resolve_store(). Reports which rule chose SECRETS_DIR.
@@ -98,6 +100,56 @@ get_pubkey() {
   age-keygen -y "$KEY_FILE" 2>/dev/null || die "Failed to derive public key from $KEY_FILE"
 }
 
+# A native age X25519 recipient: "age1" + exactly 58 chars of [0-9a-z].
+# This is also the injection rail — it cannot hold shell metacharacters,
+# whitespace, control chars, or extra flags. SSH recipients are intentionally
+# unsupported (EGB-283 scope cut).
+_validate_age_recipient() {
+  case "$1" in
+    age1*) : ;;
+    *) return 1 ;;
+  esac
+  local body="${1#age1}"
+  [ "${#body}" -eq 58 ] || return 1
+  case "$body" in
+    *[!0-9a-z]*) return 1 ;;
+  esac
+  return 0
+}
+
+# Populate the global RECIPIENT_ARGS array with one "-r <key>" per store
+# recipient. recipients.txt present -> validated keys from the file (the store
+# is multi-recipient). Absent -> the single pubkey derived from key.txt (legacy
+# single-key store, exactly today's behavior). We parse the file ourselves
+# (never `age -R <path>`) because it is committed = an injection surface; every
+# line is validated and the file is refused if symlinked. Dies on any problem.
+RECIPIENT_ARGS=()
+_load_recipients() {
+  RECIPIENT_ARGS=()
+  if [ ! -e "$RECIPIENTS_FILE" ]; then
+    RECIPIENT_ARGS=(-r "$(get_pubkey)")
+    return 0
+  fi
+  if [ -L "$RECIPIENTS_FILE" ]; then
+    die "Refusing to read symlinked $RECIPIENTS_FILE_NAME (security)."
+  fi
+  local line trimmed n=0
+  while IFS= read -r line || [ -n "$line" ]; do
+    trimmed="${line#"${line%%[![:space:]]*}"}"     # lstrip
+    trimmed="${trimmed%"${trimmed##*[![:space:]]}"}" # rstrip
+    [ -z "$trimmed" ] && continue
+    case "$trimmed" in '#'*) continue ;; esac
+    if ! _validate_age_recipient "$trimmed"; then
+      die "Invalid recipient in $RECIPIENTS_FILE_NAME: '$trimmed' (expected a native age key: age1...)."
+    fi
+    RECIPIENT_ARGS+=(-r "$trimmed")
+    n=$((n + 1))
+  done < "$RECIPIENTS_FILE"
+  if [ "$n" -eq 0 ]; then
+    die "$RECIPIENTS_FILE_NAME has no recipients — a store must have at least one. Run 'secrets recipients add <age1...>'."
+  fi
+}
+
 derive_project_name() {
   local explicit="${1:-}"
   if [ -n "$explicit" ]; then
@@ -299,6 +351,7 @@ resolve_store() {
 
   SECRETS_DIR="$resolved"
   KEY_FILE="$SECRETS_DIR/key.txt"
+  RECIPIENTS_FILE="$SECRETS_DIR/$RECIPIENTS_FILE_NAME"
   STORE_SOURCE="$source"
 }
 
@@ -630,7 +683,7 @@ merge_gradle_keys() {
 # <project>/external/. Returns 0 if at least one entry was pushed, 1 if
 # there is no usable manifest. Dies on unsafe targets or all-missing keys.
 push_external_files() {
-  local root="$1" project="$2" pubkey="$3"
+  local root="$1" project="$2"
   # Entries come from .secrets.json (EGB-677) plus any legacy
   # .secrets-files entries the manifest doesn't cover yet.
   local entries
@@ -652,7 +705,7 @@ push_external_files() {
       # EGB-652: whole-file sync — encrypt the file verbatim (binary-safe).
       mkdir -p "$SECRETS_DIR/$project/external"
       local fslug; fslug=$(_secrets_files_slug "$mpath")
-      age -r "$pubkey" -o "$SECRETS_DIR/$project/external/$fslug.$(_external_blob_suffix file).age" "$expanded"
+      age "${RECIPIENT_ARGS[@]}" -o "$SECRETS_DIR/$project/external/$fslug.$(_external_blob_suffix file).age" "$expanded"
       info "Encrypted file $mpath"
       pushed=$((pushed + 1))
       continue
@@ -681,7 +734,7 @@ push_external_files() {
     fi
     mkdir -p "$SECRETS_DIR/$project/external"
     local slug; slug=$(_secrets_files_slug "$mpath")
-    age -r "$pubkey" -o "$SECRETS_DIR/$project/external/$slug.$(_external_blob_suffix "$mtype").age" "$tmp"
+    age "${RECIPIENT_ARGS[@]}" -o "$SECRETS_DIR/$project/external/$slug.$(_external_blob_suffix "$mtype").age" "$tmp"
     rm -f "$tmp"
     info "Extracted $found key(s) from $mpath"
     pushed=$((pushed + 1))
@@ -1189,7 +1242,6 @@ Your key file has been left untouched."
 push_dir_to_project() {
   local source_dir="$1"
   local project="$2"
-  local pubkey="$3"
 
   if ! collect_env_files "$source_dir"; then
     return 1
@@ -1204,7 +1256,7 @@ push_dir_to_project() {
   for f in "${COLLECTED_FILES[@]}"; do
     local name
     name=$(basename "$f")
-    age -r "$pubkey" -o "$SECRETS_DIR/$project/${name}.age" "$f"
+    age "${RECIPIENT_ARGS[@]}" -o "$SECRETS_DIR/$project/${name}.age" "$f"
   done
   return 0
 }
@@ -1265,8 +1317,7 @@ cmd_push() {
   info "Pushing secrets for project: $project"
   echo_store_if_non_default
 
-  local pubkey
-  pubkey=$(get_pubkey)
+  _load_recipients
 
   # ── Manifest read (validated; absence = bootstrap) ──
   # jq is required only when a manifest exists (authoritative, can't be
@@ -1354,7 +1405,7 @@ cmd_push() {
       */*) mkdir -p "$SECRETS_DIR/$project/$(dirname "$rel")" ;;
       *)   mkdir -p "$SECRETS_DIR/$project" ;;
     esac
-    age -r "$pubkey" -o "$SECRETS_DIR/$project/${rel}.age" "$PWD/$rel"
+    age "${RECIPIENT_ARGS[@]}" -o "$SECRETS_DIR/$project/${rel}.age" "$PWD/$rel"
     echo "  $rel"
     count=$((count + 1))
   done <<< "$sync_list"
@@ -1362,7 +1413,7 @@ cmd_push() {
 
   local did=0
   [ "$count" -gt 0 ] && did=1
-  if push_external_files "$PWD" "$project" "$pubkey"; then did=1; fi
+  if push_external_files "$PWD" "$project"; then did=1; fi
   if [ "$did" -eq 0 ]; then
     die "No secret files (.env, .env.*, .dev.vars) or $SECRETS_FILES_NAME entries found in $PWD"
   fi
@@ -1424,12 +1475,11 @@ cmd_push_workspaces() {
   info "Pushing workspaces for monorepo: $monorepo_name"
   echo_store_if_non_default
 
-  local pubkey
-  pubkey=$(get_pubkey)
+  _load_recipients
   local total=0
 
   # Push root env files (if any)
-  if push_dir_to_project "$root" "$monorepo_name" "$pubkey"; then
+  if push_dir_to_project "$root" "$monorepo_name"; then
     total=$((total + ${#COLLECTED_FILES[@]}))
   fi
 
@@ -1440,14 +1490,14 @@ cmd_push_workspaces() {
     [ -n "$ws" ] || continue
     local ws_dir="$root/$ws"
     local ws_project="$monorepo_name/$ws"
-    if push_dir_to_project "$ws_dir" "$ws_project" "$pubkey"; then
+    if push_dir_to_project "$ws_dir" "$ws_project"; then
       total=$((total + ${#COLLECTED_FILES[@]}))
     fi
   done <<< "$workspaces"
 
   # External files (.secrets-files) are monorepo-root-scoped, like
   # .secrets-store — handle once, not per-workspace.
-  if push_external_files "$root" "$monorepo_name" "$pubkey"; then
+  if push_external_files "$root" "$monorepo_name"; then
     total=$((total + 1))
   fi
 
diff --git a/test/recipients.bats b/test/recipients.bats
new file mode 100644
index 0000000..a8ae7c6
--- /dev/null
+++ b/test/recipients.bats
@@ -0,0 +1,57 @@
+#!/usr/bin/env bats
+load test_helper
+
+# A throwaway second identity for "another teammate".
+make_second_identity() {
+  age-keygen -o "$TEST_TMPDIR/bob.txt" 2>/dev/null
+  BOB_PUB=$(age-keygen -y "$TEST_TMPDIR/bob.txt")
+}
+
+@test "push without recipients.txt stays single-key (legacy behavior)" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+  # No recipients.txt was created by push.
+  [ ! -e "$SECRETS_DIR/recipients.txt" ]
+  # Blob decrypts with the store's own key.
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "push with a hand-written recipients.txt encrypts to every listed key" {
+  init_with_remote
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '# self\n%s\n# bob\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+  # Bob (a recipient) can decrypt the pushed blob with HIS key.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
+  [ "$status" -eq 0 ]
+  # And the store key still can too.
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "push refuses a recipients.txt with an invalid key" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\nnot-an-age-key\n' "$STORE_PUB" > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid recipient"* ]] || false
+}
+
+@test "push refuses a symlinked recipients.txt" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n' "$STORE_PUB" > "$TEST_TMPDIR/elsewhere.txt"
+  ln -s "$TEST_TMPDIR/elsewhere.txt" "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"symlink"* ]] || false
+}
diff --git a/test/test_helper.bash b/test/test_helper.bash
index 1470caf..d9846af 100644
--- a/test/test_helper.bash
+++ b/test/test_helper.bash
@@ -19,6 +19,14 @@ setup() {
   # not be a real ancestor of /tmp). EGB-281 F9.
   export HOME="$TEST_TMPDIR"
 
+  # Provide git author identity so `git commit` works with the fresh temp HOME
+  # (no ~/.gitconfig is present in the isolated dir). GIT_* env vars override
+  # any global config and survive the HOME redirect.
+  export GIT_AUTHOR_NAME="Test User"
+  export GIT_AUTHOR_EMAIL="test@example.com"
+  export GIT_COMMITTER_NAME="Test User"
+  export GIT_COMMITTER_EMAIL="test@example.com"
+
   # Secrets repo lives in temp
   export SECRETS_DIR="$TEST_TMPDIR/secrets-repo"
 

From 14cf86fba9890784712e25fd8e537bd60d812e28 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 12:37:55 -0700
Subject: [PATCH 04/20] docs: plan fixups from Task 1 review (blob path,
 dangling-symlink fix to Task 8)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...26-06-24-multi-recipient-age-encryption.md | 52 +++++++++++++++----
 1 file changed, 41 insertions(+), 11 deletions(-)

diff --git a/docs/superpowers/plans/2026-06-24-multi-recipient-age-encryption.md b/docs/superpowers/plans/2026-06-24-multi-recipient-age-encryption.md
index 96a1b3a..54a38d8 100644
--- a/docs/superpowers/plans/2026-06-24-multi-recipient-age-encryption.md
+++ b/docs/superpowers/plans/2026-06-24-multi-recipient-age-encryption.md
@@ -62,7 +62,7 @@ make_second_identity() {
   # No recipients.txt was created by push.
   [ ! -e "$SECRETS_DIR/recipients.txt" ]
   # Blob decrypts with the store's own key.
-  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
 }
 
@@ -75,10 +75,10 @@ make_second_identity() {
   run "$SECRETS_BIN" push
   [ "$status" -eq 0 ]
   # Bob (a recipient) can decrypt the pushed blob with HIS key.
-  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
   # And the store key still can too.
-  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
 }
 
@@ -361,18 +361,18 @@ git commit -m "feat: secrets recipients list (EGB-283)"
 @test "reencrypt re-encrypts existing blobs to a newly added recipient line" {
   init_with_remote
   create_project_dir myproj
-  run "$SECRETS_BIN" push           # single-key blob
+  run "$SECRETS_BIN" push           # single-key blob (project name = "myproj"; blob at $SECRETS_DIR/myproj/.env.age)
   [ "$status" -eq 0 ]
   make_second_identity
   STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
   printf '%s\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
   # Bob cannot read the old single-key blob yet.
-  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -ne 0 ]
   run "$SECRETS_BIN" reencrypt
   [ "$status" -eq 0 ]
   # Now he can.
-  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
 }
 
@@ -389,7 +389,7 @@ git commit -m "feat: secrets recipients list (EGB-283)"
   # No new keypair was generated.
   [ "$(cat "$SECRETS_DIR/key.txt")" = "$before" ]
   # Both recipients can decrypt.
-  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
 }
 
@@ -401,7 +401,7 @@ git commit -m "feat: secrets recipients list (EGB-283)"
   run "$SECRETS_BIN" rekey
   [ "$status" -eq 0 ]
   [ "$(cat "$SECRETS_DIR/key.txt")" != "$before" ]
-  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
 }
 ```
@@ -562,7 +562,7 @@ git commit -m "feat: shared _reencrypt_all + reencrypt cmd + dual rekey (EGB-283
   [[ "$output" == *"recipients: 2"* ]] || false
   [[ "$output" == *"bob"* ]] || false
   # Existing blob re-encrypted: bob can read it.
-  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
 }
 
@@ -696,7 +696,7 @@ git commit -m "feat: secrets recipients add (EGB-283)"
   run "$SECRETS_BIN" recipients list
   [[ "$output" == *"recipients: 1"* ]] || false
   # Store key still reads its own blobs.
-  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/work/myproj/.env.age"
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
 }
 
@@ -1023,12 +1023,42 @@ git commit -m "feat: verify asserts blob recipient-count matches recipients.txt
 ### Task 8: Security regression fixtures for `recipients.txt`
 
 **Files:**
-- Modify: `test/recipients.bats` (adversarial fixtures only — no `secrets` changes expected; if a case slips through, fix the rail in `secrets` here)
+- Modify: `secrets` (one ordering fix in `_load_recipients`, carried over from the Task 1 review); `test/recipients.bats` (adversarial fixtures; if any other case slips through, fix the rail in `secrets` here)
 
 **Interfaces:** none new — exercises `_load_recipients` / `_recipients_add` rails via the CLI.
 
 > Policy reminder: these are ordinary defensive regression tests. Do NOT dispatch red-team/adversarial-review subagents and do NOT run `./test/run-security.sh` — that is operator-local.
 
+- [ ] **Step 0: Fix the dangling-symlink ordering gap (from Task 1 review)**
+
+In `_load_recipients`, the `[ ! -e "$RECIPIENTS_FILE" ]` check runs BEFORE the `[ -L "$RECIPIENTS_FILE" ]` check. A *dangling* symlink (link exists, target missing) makes `[ ! -e ]` true, so it bypasses the symlink refusal and silently degrades to legacy single-key mode. Swap the order so the symlink check comes first:
+
+```bash
+_load_recipients() {
+  RECIPIENT_ARGS=()
+  if [ -L "$RECIPIENTS_FILE" ]; then
+    die "Refusing to read symlinked $RECIPIENTS_FILE_NAME (security)."
+  fi
+  if [ ! -e "$RECIPIENTS_FILE" ]; then
+    RECIPIENT_ARGS=(-r "$(get_pubkey)")
+    return 0
+  fi
+  # … rest unchanged (line-by-line parse + validate) …
+```
+
+Add a regression test alongside the other SECURITY fixtures:
+
+```bash
+@test "SECURITY: a dangling symlink recipients.txt is refused, not silently ignored" {
+  init_with_remote
+  ln -s "$TEST_TMPDIR/does-not-exist.txt" "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"symlink"* ]] || false
+}
+```
+
 - [ ] **Step 1: Write the fixtures**
 
 ```bash

From 649aa7806317582d1d04a800b29d6e33aed63e2d Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 12:39:52 -0700
Subject: [PATCH 05/20] feat: secrets recipients list (EGB-283)

---
 secrets              | 51 ++++++++++++++++++++++++++++++++++++++++++++
 test/recipients.bats | 21 ++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/secrets b/secrets
index a2f5209..b10f956 100755
--- a/secrets
+++ b/secrets
@@ -150,6 +150,29 @@ _load_recipients() {
   fi
 }
 
+# Emit "<key>\t<name>" for each recipient in recipients.txt. <name> is the most
+# recent preceding "# <name>" comment, or empty. Read-only; no validation
+# (callers that need rails call _load_recipients separately).
+_recipients_dump() {
+  [ -e "$RECIPIENTS_FILE" ] || return 0
+  local line trimmed name=""
+  while IFS= read -r line || [ -n "$line" ]; do
+    trimmed="${line#"${line%%[![:space:]]*}"}"
+    trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
+    [ -z "$trimmed" ] && continue
+    case "$trimmed" in
+      '#'*)
+        name="${trimmed#\#}"
+        name="${name#"${name%%[![:space:]]*}"}"
+        ;;
+      *)
+        printf '%s\t%s\n' "$trimmed" "$name"
+        name=""
+        ;;
+    esac
+  done < "$RECIPIENTS_FILE"
+}
+
 derive_project_name() {
   local explicit="${1:-}"
   if [ -n "$explicit" ]; then
@@ -1954,6 +1977,33 @@ cmd_run() {
   exit "$rc"
 }
 
+cmd_recipients() {
+  resolve_store
+  local sub="${1:-list}"
+  [ $# -gt 0 ] && shift
+  case "$sub" in
+    list) _recipients_list ;;
+    *) die "Unknown recipients subcommand: '$sub'. Usage: secrets recipients [list]" ;;
+  esac
+}
+
+_recipients_list() {
+  check_initialized
+  if [ ! -e "$RECIPIENTS_FILE" ]; then
+    check_key
+    echo "recipients: single-key (no $RECIPIENTS_FILE_NAME)"
+    echo "  $(get_pubkey)"
+    return 0
+  fi
+  _load_recipients   # validates the file (dies on bad key / symlink)
+  local count=0 k n
+  while IFS=$'\t' read -r k n; do count=$((count + 1)); done < <(_recipients_dump)
+  echo "recipients: $count (from $RECIPIENTS_FILE_NAME)"
+  while IFS=$'\t' read -r k n; do
+    if [ -n "$n" ]; then echo "  $k  ($n)"; else echo "  $k"; fi
+  done < <(_recipients_dump)
+}
+
 cmd_which() {
   resolve_store
   echo "store:  $SECRETS_DIR"
@@ -2564,6 +2614,7 @@ case "${1:-help}" in
   rekey)  cmd_rekey ;;
   verify) shift; cmd_verify "$@" ;;
   migrate) shift; cmd_migrate "$@" ;;
+  recipients) shift; cmd_recipients "$@" ;;
   which|where|status) cmd_which ;;
   help|--help|-h) cmd_help ;;
   *)      die "Unknown command: $1. Run 'secrets help' for usage." ;;
diff --git a/test/recipients.bats b/test/recipients.bats
index a8ae7c6..87e5491 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -55,3 +55,24 @@ make_second_identity() {
   [ "$status" -ne 0 ]
   [[ "$output" == *"symlink"* ]] || false
 }
+
+@test "recipients list on a legacy store shows the single derived key" {
+  init_with_remote
+  run "$SECRETS_BIN" recipients list
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"single-key"* ]] || false
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  [[ "$output" == *"$STORE_PUB"* ]] || false
+}
+
+@test "recipients list shows names and keys from recipients.txt" {
+  init_with_remote
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '# alice\n%s\n# bob\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  run "$SECRETS_BIN" recipients list
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"recipients: 2"* ]] || false
+  [[ "$output" == *"alice"* ]] || false
+  [[ "$output" == *"bob"* ]] || false
+}

From a10f390519ed194b621feb06b14795f53e46c97b Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 12:44:44 -0700
Subject: [PATCH 06/20] feat: shared _reencrypt_all + reencrypt cmd + dual
 rekey (EGB-283)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 secrets              | 87 +++++++++++++++++++++++++++++++++++++++++++-
 test/recipients.bats | 47 ++++++++++++++++++++++++
 2 files changed, 133 insertions(+), 1 deletion(-)

diff --git a/secrets b/secrets
index b10f956..123c556 100755
--- a/secrets
+++ b/secrets
@@ -1772,6 +1772,78 @@ cmd_rm() {
   fi
 }
 
+# Decrypt every blob in the store with the local key and re-encrypt each to the
+# currently-loaded RECIPIENT_ARGS, then commit + push. The caller MUST have run
+# _load_recipients (or set RECIPIENT_ARGS) and check_key first. Aborts with the
+# store untouched on any decrypt failure (you must be a current recipient).
+# Shared by recipients add/rm, reencrypt, and multi-recipient rekey.
+_reencrypt_all() {
+  local commit_msg="$1"
+  local tmpdir
+  tmpdir=$(mktemp -d)
+  trap 'rm -rf "${tmpdir:-}"' EXIT INT TERM
+
+  info "Decrypting all blobs with your key..."
+  local file_count=0 dir project f rel dest
+  for dir in "$SECRETS_DIR"/*/; do
+    [ -d "$dir" ] || continue
+    project=$(basename "$dir")
+    case "$project" in .*) continue ;; esac
+    mkdir -p "$tmpdir/$project"
+    while IFS= read -r f; do
+      [ -f "$f" ] || continue
+      rel=${f#"$dir"}; rel=${rel%.age}
+      dest="$tmpdir/$project/$rel"
+      mkdir -p "$(dirname "$dest")"
+      if ! age -d -i "$KEY_FILE" -o "$dest" "$f"; then
+        die "Decryption failed for $project/$rel (are you a current recipient?). Aborted; store unchanged."
+      fi
+      file_count=$((file_count + 1))
+    done < <(find "$dir" -type f -name '*.age')
+  done
+
+  if [ "$file_count" -eq 0 ]; then
+    rm -rf "$tmpdir"; trap - EXIT INT TERM
+    info "No encrypted blobs in the store — nothing to re-encrypt."
+    return 0
+  fi
+
+  local rc=$(( ${#RECIPIENT_ARGS[@]} / 2 ))
+  info "Re-encrypting $file_count blob(s) to $rc recipient(s)..."
+  for dir in "$tmpdir"/*/; do
+    [ -d "$dir" ] || continue
+    project=$(basename "$dir")
+    mkdir -p "$SECRETS_DIR/$project"
+    while IFS= read -r f; do
+      [ -f "$f" ] || continue
+      rel=${f#"$dir"}
+      mkdir -p "$(dirname "$SECRETS_DIR/$project/$rel")"
+      age "${RECIPIENT_ARGS[@]}" -o "$SECRETS_DIR/$project/${rel}.age" "$f"
+    done < <(find "$dir" -type f)
+  done
+
+  ensure_store_protections
+  git -C "$SECRETS_DIR" add -A
+  git -C "$SECRETS_DIR" commit -m "$commit_msg" >/dev/null
+  if git -C "$SECRETS_DIR" remote get-url origin >/dev/null 2>&1; then
+    git -C "$SECRETS_DIR" push >/dev/null 2>&1
+    info "Pushed re-encrypted secrets to remote"
+  else
+    info "Committed re-encrypted secrets locally (no remote configured)"
+  fi
+  rm -rf "$tmpdir"; trap - EXIT INT TERM
+}
+
+cmd_reencrypt() {
+  check_cmd age
+  check_cmd git
+  resolve_store
+  check_initialized
+  check_key
+  _load_recipients
+  _reencrypt_all "reencrypt: re-encrypt all to current recipients"
+}
+
 cmd_rekey() {
   check_cmd age
   check_cmd git
@@ -1779,6 +1851,18 @@ cmd_rekey() {
   check_initialized
   check_key
 
+  # EGB-283: on a multi-recipient store, rekey means "re-encrypt every blob to
+  # the current recipients.txt set" — NOT a new keypair (rotating an identity is
+  # the member's own age-keygen + recipients rm/add). Legacy stores (no
+  # recipients.txt) keep the original generate-new-keypair behavior below.
+  if [ -e "$RECIPIENTS_FILE" ]; then
+    _load_recipients
+    info "Multi-recipient store — re-encrypting to $RECIPIENTS_FILE_NAME (no new key generated)."
+    _reencrypt_all "rekey: re-encrypt all to current recipients"
+    return 0
+  fi
+
+  # ── Legacy single-key rotation (unchanged) ──
   # Create temp dir with cleanup trap
   local tmpdir
   tmpdir=$(mktemp -d)
@@ -2611,7 +2695,8 @@ case "${1:-help}" in
   add)    cmd_add "${2:-}" ;;
   list)   cmd_list ;;
   rm)     cmd_rm "${2:-}" ;;
-  rekey)  cmd_rekey ;;
+  rekey)      cmd_rekey ;;
+  reencrypt)  cmd_reencrypt ;;
   verify) shift; cmd_verify "$@" ;;
   migrate) shift; cmd_migrate "$@" ;;
   recipients) shift; cmd_recipients "$@" ;;
diff --git a/test/recipients.bats b/test/recipients.bats
index 87e5491..c5be2dd 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -76,3 +76,50 @@ make_second_identity() {
   [[ "$output" == *"alice"* ]] || false
   [[ "$output" == *"bob"* ]] || false
 }
+
+@test "reencrypt re-encrypts existing blobs to a newly added recipient line" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push           # single-key blob (project name = "myproj"; blob at $SECRETS_DIR/myproj/.env.age)
+  [ "$status" -eq 0 ]
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  # Bob cannot read the old single-key blob yet.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
+  [ "$status" -ne 0 ]
+  run "$SECRETS_BIN" reencrypt
+  [ "$status" -eq 0 ]
+  # Now he can.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "rekey on a multi-recipient store keeps recipients and the same key" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  before=$(cat "$SECRETS_DIR/key.txt")
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  run "$SECRETS_BIN" rekey
+  [ "$status" -eq 0 ]
+  # No new keypair was generated.
+  [ "$(cat "$SECRETS_DIR/key.txt")" = "$before" ]
+  # Both recipients can decrypt.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "rekey on a legacy store still rotates to a new key (unchanged)" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  before=$(cat "$SECRETS_DIR/key.txt")
+  run "$SECRETS_BIN" rekey
+  [ "$status" -eq 0 ]
+  [ "$(cat "$SECRETS_DIR/key.txt")" != "$before" ]
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}

From c2626610305f589911404e93d55bde9ba66dca7e Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 12:50:00 -0700
Subject: [PATCH 07/20] feat: secrets recipients add (EGB-283)

Add `secrets recipients add <age1...> [--name <label>]`: validates the
age key and optional display name, bootstraps recipients.txt with the
local pubkey on a legacy store (keeping the operator as a recipient),
rejects duplicates, appends the new key (with optional name comment),
then re-encrypts the entire store to the updated recipient list.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 secrets              | 48 +++++++++++++++++++++++++++++++++++++++++++-
 test/recipients.bats | 42 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+), 1 deletion(-)

diff --git a/secrets b/secrets
index 123c556..7009da4 100755
--- a/secrets
+++ b/secrets
@@ -117,6 +117,15 @@ _validate_age_recipient() {
   return 0
 }
 
+# Recipient display names become "# <name>" comment lines in recipients.txt.
+# Restrict to a safe charset so a name can't inject extra lines/metacharacters.
+_validate_recipient_name() {
+  case "$1" in
+    *[!A-Za-z0-9\ ._-]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
 # Populate the global RECIPIENT_ARGS array with one "-r <key>" per store
 # recipient. recipients.txt present -> validated keys from the file (the store
 # is multi-recipient). Absent -> the single pubkey derived from key.txt (legacy
@@ -2067,7 +2076,8 @@ cmd_recipients() {
   [ $# -gt 0 ] && shift
   case "$sub" in
     list) _recipients_list ;;
-    *) die "Unknown recipients subcommand: '$sub'. Usage: secrets recipients [list]" ;;
+    add)  _recipients_add "$@" ;;
+    *) die "Unknown recipients subcommand: '$sub'. Usage: secrets recipients [list|add <age1...> [--name N]]" ;;
   esac
 }
 
@@ -2088,6 +2098,42 @@ _recipients_list() {
   done < <(_recipients_dump)
 }
 
+_recipients_add() {
+  check_cmd age
+  check_cmd git
+  check_initialized
+  check_key
+  local key="" name=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --name) name="${2:-}"; shift 2 ;;
+      -*) die "Unknown flag: $1. Usage: secrets recipients add <age1...> [--name <label>]" ;;
+      *) if [ -z "$key" ]; then key="$1"; else die "Unexpected argument: $1"; fi; shift ;;
+    esac
+  done
+  [ -n "$key" ] || die "Usage: secrets recipients add <age1...> [--name <label>]"
+  _validate_age_recipient "$key" || die "Not a valid age recipient: '$key' (expected age1..., 62 chars; SSH keys unsupported)."
+  if [ -n "$name" ]; then
+    _validate_recipient_name "$name" || die "Invalid --name '$name' (allowed: letters, digits, space, . _ -)."
+  fi
+  if [ -L "$RECIPIENTS_FILE" ]; then
+    die "Refusing to write symlinked $RECIPIENTS_FILE_NAME."
+  fi
+  # Bootstrap a legacy store: seed this machine's key first so the operator
+  # stays a recipient (and can decrypt to re-encrypt).
+  if [ ! -e "$RECIPIENTS_FILE" ]; then
+    printf '# self\n%s\n' "$(get_pubkey)" > "$RECIPIENTS_FILE"
+  fi
+  local k _n
+  while IFS=$'\t' read -r k _n; do
+    [ "$k" = "$key" ] && die "Recipient already present: $key"
+  done < <(_recipients_dump)
+  { [ -n "$name" ] && printf '# %s\n' "$name"; printf '%s\n' "$key"; } >> "$RECIPIENTS_FILE"
+  info "Added recipient${name:+ ($name)}: $key"
+  _load_recipients
+  _reencrypt_all "recipients: add ${name:-$key}; re-encrypt all"
+}
+
 cmd_which() {
   resolve_store
   echo "store:  $SECRETS_DIR"
diff --git a/test/recipients.bats b/test/recipients.bats
index c5be2dd..05ff783 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -123,3 +123,45 @@ make_second_identity() {
   run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
 }
+
+@test "recipients add bootstraps a legacy store and re-encrypts" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  [ "$status" -eq 0 ]
+  [ -e "$SECRETS_DIR/recipients.txt" ]
+  # recipients.txt now has self + bob (2 keys).
+  run "$SECRETS_BIN" recipients list
+  [[ "$output" == *"recipients: 2"* ]] || false
+  [[ "$output" == *"bob"* ]] || false
+  # Existing blob re-encrypted: bob can read it.
+  run age -d -i "$TEST_TMPDIR/bob.txt" "$SECRETS_DIR/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "recipients add rejects a non-age key" {
+  init_with_remote
+  run "$SECRETS_BIN" recipients add "ssh-ed25519 AAAAfoo"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"valid age recipient"* ]] || false
+}
+
+@test "recipients add rejects a duplicate" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  [ "$status" -eq 0 ]
+  run "$SECRETS_BIN" recipients add "$BOB_PUB"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"already present"* ]] || false
+}
+
+@test "recipients add rejects an unsafe --name" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name 'bob; rm -rf ~'
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid --name"* ]] || false
+}

From 4ba0234bd7499bb44d3d3882c33fac31874f362d Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 12:53:27 -0700
Subject: [PATCH 08/20] fix: harden recipients add --name validation (EGB-283)

Require a non-empty argument after --name (dies if it is the last token)
and reject whitespace-only labels that would write a blank comment line.
Two regression tests added to test/recipients.bats.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 secrets              |  5 ++++-
 test/recipients.bats | 16 ++++++++++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/secrets b/secrets
index 7009da4..7015a40 100755
--- a/secrets
+++ b/secrets
@@ -2106,7 +2106,7 @@ _recipients_add() {
   local key="" name=""
   while [ $# -gt 0 ]; do
     case "$1" in
-      --name) name="${2:-}"; shift 2 ;;
+      --name) [ $# -ge 2 ] || die "--name requires a value."; name="$2"; shift 2 ;;
       -*) die "Unknown flag: $1. Usage: secrets recipients add <age1...> [--name <label>]" ;;
       *) if [ -z "$key" ]; then key="$1"; else die "Unexpected argument: $1"; fi; shift ;;
     esac
@@ -2114,6 +2114,9 @@ _recipients_add() {
   [ -n "$key" ] || die "Usage: secrets recipients add <age1...> [--name <label>]"
   _validate_age_recipient "$key" || die "Not a valid age recipient: '$key' (expected age1..., 62 chars; SSH keys unsupported)."
   if [ -n "$name" ]; then
+    # Reject a whitespace-only label (would write a blank "# " comment line).
+    local _name_stripped="${name//[[:space:]]/}"
+    [ -n "$_name_stripped" ] || die "Invalid --name: must contain a non-space character."
     _validate_recipient_name "$name" || die "Invalid --name '$name' (allowed: letters, digits, space, . _ -)."
   fi
   if [ -L "$RECIPIENTS_FILE" ]; then
diff --git a/test/recipients.bats b/test/recipients.bats
index 05ff783..6c00c89 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -165,3 +165,19 @@ make_second_identity() {
   [ "$status" -ne 0 ]
   [[ "$output" == *"Invalid --name"* ]] || false
 }
+
+@test "recipients add rejects a whitespace-only --name" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name '   '
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid --name"* ]] || false
+}
+
+@test "recipients add --name with no value errors" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"--name requires a value"* ]] || false
+}

From cad5b66f77fa017524b68d72805164b0590ad8d6 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 12:56:50 -0700
Subject: [PATCH 09/20] feat: secrets recipients rm with lockout guards
 (EGB-283)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 secrets              | 52 +++++++++++++++++++++++++++++++++++++++++++-
 test/recipients.bats | 48 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+), 1 deletion(-)

diff --git a/secrets b/secrets
index 7015a40..aa6212b 100755
--- a/secrets
+++ b/secrets
@@ -2077,7 +2077,8 @@ cmd_recipients() {
   case "$sub" in
     list) _recipients_list ;;
     add)  _recipients_add "$@" ;;
-    *) die "Unknown recipients subcommand: '$sub'. Usage: secrets recipients [list|add <age1...> [--name N]]" ;;
+    rm|remove) _recipients_rm "$@" ;;
+    *) die "Unknown recipients subcommand: '$sub'. Usage: secrets recipients [list|add <age1...> [--name N]|rm <age1...|name> [--yes]]" ;;
   esac
 }
 
@@ -2137,6 +2138,55 @@ _recipients_add() {
   _reencrypt_all "recipients: add ${name:-$key}; re-encrypt all"
 }
 
+# Rewrite recipients.txt canonically (one "# name"? + key per entry), dropping
+# the entry whose key == <drop>. Atomic-ish via temp file in the same dir.
+_recipients_write_without() {
+  local drop="$1" tmp k n
+  tmp=$(mktemp "$SECRETS_DIR/.recipients.XXXXXX")
+  while IFS=$'\t' read -r k n; do
+    [ "$k" = "$drop" ] && continue
+    [ -n "$n" ] && printf '# %s\n' "$n" >> "$tmp"
+    printf '%s\n' "$k" >> "$tmp"
+  done < <(_recipients_dump)
+  mv "$tmp" "$RECIPIENTS_FILE"
+}
+
+_recipients_rm() {
+  check_cmd age
+  check_cmd git
+  check_initialized
+  check_key
+  local target="" assume_yes=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --yes|-y) assume_yes=true; shift ;;
+      -*) die "Unknown flag: $1. Usage: secrets recipients rm <age1...|name> [--yes]" ;;
+      *) if [ -z "$target" ]; then target="$1"; else die "Unexpected argument: $1"; fi; shift ;;
+    esac
+  done
+  [ -n "$target" ] || die "Usage: secrets recipients rm <age1...|name> [--yes]"
+  [ -e "$RECIPIENTS_FILE" ] || die "No $RECIPIENTS_FILE_NAME — store is single-key; nothing to remove."
+  [ -L "$RECIPIENTS_FILE" ] && die "Refusing to write symlinked $RECIPIENTS_FILE_NAME."
+  local k n match="" count=0 total=0
+  while IFS=$'\t' read -r k n; do
+    total=$((total + 1))
+    if [ "$k" = "$target" ] || { [ -n "$n" ] && [ "$n" = "$target" ]; }; then
+      match="$k"; count=$((count + 1))
+    fi
+  done < <(_recipients_dump)
+  [ "$count" -eq 0 ] && die "No recipient matches '$target'."
+  [ "$count" -gt 1 ] && die "'$target' matches $count recipients by name — remove by key (age1...) instead."
+  [ "$total" -le 1 ] && die "Refusing to remove the last recipient — a store must have at least one."
+  local self; self="$(get_pubkey)"
+  if [ "$match" = "$self" ] && [ "$assume_yes" != true ]; then
+    die "Refusing to remove your own key (you would lose access to future pushes). Re-run with --yes to confirm."
+  fi
+  _recipients_write_without "$match"
+  info "Removed recipient: $match"
+  _load_recipients
+  _reencrypt_all "recipients: remove $match; re-encrypt all"
+}
+
 cmd_which() {
   resolve_store
   echo "store:  $SECRETS_DIR"
diff --git a/test/recipients.bats b/test/recipients.bats
index 6c00c89..6067754 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -181,3 +181,51 @@ make_second_identity() {
   [ "$status" -ne 0 ]
   [[ "$output" == *"--name requires a value"* ]] || false
 }
+
+@test "recipients rm removes a recipient and re-encrypts to the rest" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  run "$SECRETS_BIN" recipients rm bob
+  [ "$status" -eq 0 ]
+  run "$SECRETS_BIN" recipients list
+  [[ "$output" == *"recipients: 1"* ]] || false
+  # Store key still reads its own blobs.
+  run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
+  [ "$status" -eq 0 ]
+}
+
+@test "recipients rm refuses to remove the last recipient" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob   # store = self + bob
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  run "$SECRETS_BIN" recipients rm bob                       # back to self only
+  [ "$status" -eq 0 ]
+  run "$SECRETS_BIN" recipients rm "$STORE_PUB"              # would be the last
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"last recipient"* ]] || false
+}
+
+@test "recipients rm of your own key requires --yes" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  run "$SECRETS_BIN" recipients rm "$STORE_PUB"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"your own key"* ]] || false
+  run "$SECRETS_BIN" recipients rm "$STORE_PUB" --yes
+  [ "$status" -eq 0 ]
+}
+
+@test "recipients rm of a non-existent target errors" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  run "$SECRETS_BIN" recipients rm carol
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"No recipient matches"* ]] || false
+}

From 50b73083f1a80225038ea668aa709496fb646ac5 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 13:03:20 -0700
Subject: [PATCH 10/20] feat: init born-multi recipients.txt + which recipients
 line (EGB-283)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 secrets              | 21 +++++++++++++++++++++
 test/recipients.bats | 34 ++++++++++++++++++++++++++++++----
 2 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/secrets b/secrets
index aa6212b..77ee0bf 100755
--- a/secrets
+++ b/secrets
@@ -1260,6 +1260,11 @@ Your key file has been left untouched."
   local pubkey
   pubkey=$(get_pubkey)
 
+  # EGB-283: born-multi — seed recipients.txt with this store's public key so
+  # the store is multi-recipient-ready from day one. Committed (not gitignored),
+  # staged by the first push like .secrets-format.
+  printf '# self\n%s\n' "$pubkey" > "$RECIPIENTS_FILE"
+
   info "Done! Your public key is:"
   echo "  $pubkey"
   echo ""
@@ -2195,6 +2200,22 @@ cmd_which() {
   # v1 from v2 during the migration window. v1 = legacy store, no format marker.
   echo "format: v$(_store_format)"
 
+  # EGB-283: surface the recipient set (store-scoped; one key per team member).
+  if [ -e "$RECIPIENTS_FILE" ] && [ ! -L "$RECIPIENTS_FILE" ]; then
+    local rcount=0 rk rn rnames=""
+    while IFS=$'\t' read -r rk rn; do
+      rcount=$((rcount + 1))
+      [ -n "$rn" ] && rnames="${rnames:+$rnames, }$rn"
+    done < <(_recipients_dump)
+    if [ -n "$rnames" ]; then
+      echo "recipients: $rcount ($rnames)"
+    else
+      echo "recipients: $rcount"
+    fi
+  else
+    echo "recipients: single-key (no $RECIPIENTS_FILE_NAME)"
+  fi
+
   # v2 manifest (.secrets.json): validate and summarize. Validation here
   # is deliberately fatal (symlink / malformed / unsupported version) so
   # `secrets which` doubles as the manifest linter.
diff --git a/test/recipients.bats b/test/recipients.bats
index 6067754..6c73759 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -7,14 +7,14 @@ make_second_identity() {
   BOB_PUB=$(age-keygen -y "$TEST_TMPDIR/bob.txt")
 }
 
-@test "push without recipients.txt stays single-key (legacy behavior)" {
+@test "push with only-self recipients.txt encrypts to the store key (born-multi)" {
   init_with_remote
+  # init now seeds recipients.txt with self — born-multi store.
+  [ -e "$SECRETS_DIR/recipients.txt" ]
   create_project_dir myproj
   run "$SECRETS_BIN" push
   [ "$status" -eq 0 ]
-  # No recipients.txt was created by push.
-  [ ! -e "$SECRETS_DIR/recipients.txt" ]
-  # Blob decrypts with the store's own key.
+  # Blob must still decrypt with the store's own key.
   run age -d -i "$SECRETS_DIR/key.txt" "$SECRETS_DIR/myproj/.env.age"
   [ "$status" -eq 0 ]
 }
@@ -49,6 +49,8 @@ make_second_identity() {
   init_with_remote
   STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
   printf '%s\n' "$STORE_PUB" > "$TEST_TMPDIR/elsewhere.txt"
+  # Remove the born-multi recipients.txt so we can replace it with a symlink.
+  rm -f "$SECRETS_DIR/recipients.txt"
   ln -s "$TEST_TMPDIR/elsewhere.txt" "$SECRETS_DIR/recipients.txt"
   create_project_dir myproj
   run "$SECRETS_BIN" push
@@ -58,6 +60,8 @@ make_second_identity() {
 
 @test "recipients list on a legacy store shows the single derived key" {
   init_with_remote
+  # Simulate a legacy store by removing the born-multi recipients.txt.
+  rm -f "$SECRETS_DIR/recipients.txt"
   run "$SECRETS_BIN" recipients list
   [ "$status" -eq 0 ]
   [[ "$output" == *"single-key"* ]] || false
@@ -117,6 +121,8 @@ make_second_identity() {
   create_project_dir myproj
   run "$SECRETS_BIN" push
   before=$(cat "$SECRETS_DIR/key.txt")
+  # Simulate a legacy store by removing the born-multi recipients.txt.
+  rm -f "$SECRETS_DIR/recipients.txt"
   run "$SECRETS_BIN" rekey
   [ "$status" -eq 0 ]
   [ "$(cat "$SECRETS_DIR/key.txt")" != "$before" ]
@@ -229,3 +235,23 @@ make_second_identity() {
   [ "$status" -ne 0 ]
   [[ "$output" == *"No recipient matches"* ]] || false
 }
+
+@test "init seeds recipients.txt with the new store key (born-multi)" {
+  run "$SECRETS_BIN" init
+  [ "$status" -eq 0 ]
+  [ -e "$SECRETS_DIR/recipients.txt" ]
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  run cat "$SECRETS_DIR/recipients.txt"
+  [[ "$output" == *"$STORE_PUB"* ]] || false
+}
+
+@test "which reports the recipient count" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  create_project_dir myproj
+  run "$SECRETS_BIN" which
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"recipients: 2"* ]] || false
+  [[ "$output" == *"bob"* ]] || false
+}

From ae52b8c077d13c3c92abf4ab24ea92ed2d265ebb Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 13:06:57 -0700
Subject: [PATCH 11/20] test: restore bootstrap-path + which-legacy coverage
 (EGB-283)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 test/recipients.bats | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/test/recipients.bats b/test/recipients.bats
index 6c73759..433d46a 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -134,6 +134,9 @@ make_second_identity() {
   init_with_remote
   create_project_dir myproj
   run "$SECRETS_BIN" push
+  # Simulate a legacy store (no recipients.txt) so recipients add triggers the
+  # bootstrap branch (if [ ! -e "$RECIPIENTS_FILE" ]) rather than the append path.
+  rm -f "$SECRETS_DIR/recipients.txt"
   make_second_identity
   run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
   [ "$status" -eq 0 ]
@@ -255,3 +258,12 @@ make_second_identity() {
   [[ "$output" == *"recipients: 2"* ]] || false
   [[ "$output" == *"bob"* ]] || false
 }
+
+@test "which reports single-key for a legacy store" {
+  init_with_remote
+  rm -f "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" which
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"recipients: single-key"* ]] || false
+}

From e4cd524483726c0d2c97f49778bb7989e62f4928 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 13:10:53 -0700
Subject: [PATCH 12/20] feat: verify asserts blob recipient-count matches
 recipients.txt (EGB-283)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 secrets              | 47 ++++++++++++++++++++++++++++++++++++++++++++
 test/recipients.bats | 23 ++++++++++++++++++++++
 2 files changed, 70 insertions(+)

diff --git a/secrets b/secrets
index 77ee0bf..5711842 100755
--- a/secrets
+++ b/secrets
@@ -2266,12 +2266,45 @@ _verify_blob_decrypts() {
   age -d -i "$KEY_FILE" "$1" >/dev/null 2>&1
 }
 
+# Count age recipient stanzas ("-> ...") in a blob's header. The age v1 header
+# is ASCII and ends at the "--- <mac>" line, so reading line-by-line stops
+# before any binary body. Echoes the count.
+_blob_recipient_count() {
+  local f="$1" line count=0
+  while IFS= read -r line; do
+    case "$line" in
+      '--- '*) break ;;
+      '-> '*) count=$((count + 1)) ;;
+    esac
+  done < "$f"
+  echo "$count"
+}
+
+# If the store is multi-recipient (expected non-empty), assert <blob> was
+# encrypted to exactly <expected> recipients. Echoes a FINDING and returns 1 on
+# mismatch; returns 0 otherwise (incl. legacy stores where expected is empty).
+_check_blob_recipient_count() {
+  local blob="$1" rel="$2" expected="$3"
+  [ -n "$expected" ] || return 0
+  local actual; actual=$(_blob_recipient_count "$blob")
+  if [ "$actual" != "$expected" ]; then
+    echo "FINDING: $rel is encrypted to $actual recipient(s) but $RECIPIENTS_FILE_NAME has $expected — run 'secrets reencrypt'." >&2
+    return 1
+  fi
+  return 0
+}
+
 # `secrets verify --all` — store-wide decrypt sweep. Decrypt-tests every blob
 # in every project. No manifest consistency check: the store carries only
 # ciphertext (manifests live in each project's repo), so orphan/missing
 # detection is impossible store-wide. This is the migration integrity gate.
 _verify_all() {
   local checked=0 failed=0 dir project f rel
+  local rexpected=""
+  if [ -e "$RECIPIENTS_FILE" ] && [ ! -L "$RECIPIENTS_FILE" ]; then
+    _load_recipients   # validates; dies on a bad recipients.txt
+    rexpected=$(( ${#RECIPIENT_ARGS[@]} / 2 ))
+  fi
   for dir in "$SECRETS_DIR"/*/; do
     [ -d "$dir" ] || continue
     project=$(basename "$dir")
@@ -2287,6 +2320,9 @@ _verify_all() {
         echo "FAIL: $rel does not decrypt with the current key." >&2
         failed=$((failed + 1))
       fi
+      if ! _check_blob_recipient_count "$f" "${f#"$SECRETS_DIR"/}" "$rexpected"; then
+        failed=$((failed + 1))
+      fi
     done < <(find "$dir" -type f -name '*.age')
   done
   if [ "$checked" -eq 0 ]; then
@@ -2319,6 +2355,11 @@ _verify_project() {
   local pdir="$SECRETS_DIR/$project"
 
   local findings=0 checked=0
+  local rexpected=""
+  if [ -e "$RECIPIENTS_FILE" ] && [ ! -L "$RECIPIENTS_FILE" ]; then
+    _load_recipients   # validates; dies on a bad recipients.txt
+    rexpected=$(( ${#RECIPIENT_ARGS[@]} / 2 ))
+  fi
   # `expected` accumulates the store-relative blob paths the manifest implies,
   # newline-framed (leading + trailing \n per entry) so the orphan walk can
   # test membership. bash 3.2 has no associative arrays — this string-set +
@@ -2349,6 +2390,9 @@ _verify_project() {
       echo "FINDING: blob for '$rel' ($project/$rel.age) does not decrypt with the current key." >&2
       findings=$((findings + 1))
     fi
+    if ! _check_blob_recipient_count "$blob" "$project/$rel.age" "$rexpected"; then
+      findings=$((findings + 1))
+    fi
   done < <(jq -r '.dotenv // [] | .[]' "$manifest")
 
   # ── external entries: missing-blob + decrypt ──
@@ -2375,6 +2419,9 @@ _verify_project() {
       echo "FINDING: external blob for '$epath' ($project/$erel) does not decrypt with the current key." >&2
       findings=$((findings + 1))
     fi
+    if ! _check_blob_recipient_count "$eblob" "$project/$erel" "$rexpected"; then
+      findings=$((findings + 1))
+    fi
   done < <(_json_external_entries "$manifest")
 
   # ── orphan detection: any stored blob the manifest doesn't account for ──
diff --git a/test/recipients.bats b/test/recipients.bats
index 433d46a..c02888c 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -267,3 +267,26 @@ make_second_identity() {
   [ "$status" -eq 0 ]
   [[ "$output" == *"recipients: single-key"* ]] || false
 }
+
+@test "verify --all passes on a healthy multi-recipient store" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob   # re-encrypts to 2
+  run "$SECRETS_BIN" verify --all
+  [ "$status" -eq 0 ]
+}
+
+@test "verify flags a blob whose recipient count drifted" {
+  init_with_remote
+  create_project_dir myproj
+  run "$SECRETS_BIN" push                                   # single-key blob (1 stanza)
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  # Declare 2 recipients but do NOT re-encrypt — the on-disk blob still has 1.
+  printf '%s\n%s\n' "$STORE_PUB" "$BOB_PUB" > "$SECRETS_DIR/recipients.txt"
+  run "$SECRETS_BIN" verify --all
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"recipient"* ]] || false
+}

From 28f44f043cabb3f9dc5d1a263507af3980348a92 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 13:17:28 -0700
Subject: [PATCH 13/20] test: recipients.txt security regression fixtures +
 dangling-symlink fix (EGB-283)

Swap _load_recipients check order so [ -L ] (symlink) runs before [ ! -e ]
(missing), closing the gap where a dangling symlink bypassed the refusal
and silently fell back to legacy single-key mode.

Add 6 SECURITY-tagged fixtures to test/recipients.bats: dangling-symlink
refused (the ordering gap), shell-metachar injection (no execution), extra-
age-flag-looking line, control/ANSI chars, embedded whitespace via add, and
symlinked file refused on add. All 6 pass immediately after the ordering fix;
the existing rails (_validate_age_recipient, -L checks) were already tight
enough that only the production swap was needed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 secrets              |  6 ++---
 test/recipients.bats | 59 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/secrets b/secrets
index 5711842..421fc5f 100755
--- a/secrets
+++ b/secrets
@@ -135,13 +135,13 @@ _validate_recipient_name() {
 RECIPIENT_ARGS=()
 _load_recipients() {
   RECIPIENT_ARGS=()
+  if [ -L "$RECIPIENTS_FILE" ]; then
+    die "Refusing to read symlinked $RECIPIENTS_FILE_NAME (security)."
+  fi
   if [ ! -e "$RECIPIENTS_FILE" ]; then
     RECIPIENT_ARGS=(-r "$(get_pubkey)")
     return 0
   fi
-  if [ -L "$RECIPIENTS_FILE" ]; then
-    die "Refusing to read symlinked $RECIPIENTS_FILE_NAME (security)."
-  fi
   local line trimmed n=0
   while IFS= read -r line || [ -n "$line" ]; do
     trimmed="${line#"${line%%[![:space:]]*}"}"     # lstrip
diff --git a/test/recipients.bats b/test/recipients.bats
index c02888c..ae13b22 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -290,3 +290,62 @@ make_second_identity() {
   [ "$status" -ne 0 ]
   [[ "$output" == *"recipient"* ]] || false
 }
+
+@test "SECURITY: a dangling symlink recipients.txt is refused, not silently ignored" {
+  init_with_remote
+  rm -f "$SECRETS_DIR/recipients.txt"
+  ln -s "$TEST_TMPDIR/does-not-exist.txt" "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"symlink"* ]] || false
+}
+
+@test "SECURITY: recipients.txt with shell metacharacters is rejected, no execution" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\nage1$(touch %s/pwned)\n' "$STORE_PUB" "$TEST_TMPDIR" > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [ ! -e "$TEST_TMPDIR/pwned" ]
+  [[ "$output" == *"Invalid recipient"* ]] || false
+}
+
+@test "SECURITY: recipients.txt line that looks like an extra age flag is rejected" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n-i /etc/passwd\n' "$STORE_PUB" > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid recipient"* ]] || false
+}
+
+@test "SECURITY: control/ANSI characters in recipients.txt are rejected" {
+  init_with_remote
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\nage1%b\n' "$STORE_PUB" 'aaaa\033[31mevil' > "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  [ "$status" -ne 0 ]
+}
+
+@test "SECURITY: recipients add rejects a key with embedded whitespace" {
+  init_with_remote
+  run "$SECRETS_BIN" recipients add "age1aaaa bbbb"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"valid age recipient"* ]] || false
+}
+
+@test "SECURITY: a symlinked recipients.txt is refused on add and rm too" {
+  init_with_remote
+  make_second_identity
+  STORE_PUB=$(age-keygen -y "$SECRETS_DIR/key.txt")
+  printf '%s\n' "$STORE_PUB" > "$TEST_TMPDIR/elsewhere.txt"
+  rm -f "$SECRETS_DIR/recipients.txt"
+  ln -s "$TEST_TMPDIR/elsewhere.txt" "$SECRETS_DIR/recipients.txt"
+  run "$SECRETS_BIN" recipients add "$BOB_PUB"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"symlink"* ]] || false
+}

From b09f94c92f7a69d12bf350f9e76105e62e389188 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 13:21:33 -0700
Subject: [PATCH 14/20] test: pin security fixtures to the validation rail
 (EGB-283)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 test/recipients.bats | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/test/recipients.bats b/test/recipients.bats
index ae13b22..4c11199 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -320,6 +320,8 @@ make_second_identity() {
   run "$SECRETS_BIN" push
   [ "$status" -ne 0 ]
   [[ "$output" == *"Invalid recipient"* ]] || false
+  # The push must have aborted before encrypting — no blob should exist.
+  [ ! -e "$SECRETS_DIR/myproj/.env.age" ]
 }
 
 @test "SECURITY: control/ANSI characters in recipients.txt are rejected" {
@@ -329,6 +331,7 @@ make_second_identity() {
   create_project_dir myproj
   run "$SECRETS_BIN" push
   [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid recipient"* ]] || false
 }
 
 @test "SECURITY: recipients add rejects a key with embedded whitespace" {

From f7576a3eaecd6c07b76889d638179d0f4b377af7 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 13:25:33 -0700
Subject: [PATCH 15/20] docs: multi-recipient age encryption
 (recipients/reencrypt) + bump 0.6.2.0 (EGB-283)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md | 31 +++++++++++++++++++++++
 CLAUDE.md    | 25 ++++++++++++++++---
 README.md    | 70 +++++++++++++++++++++++++++++++++++++++++++++++++---
 VERSION      |  2 +-
 secrets      |  4 +++
 5 files changed, 125 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 774c55a..8a71b52 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to a four-digit MAJOR.MINOR.PATCH.MICRO version scheme.
 
+## [0.6.2.0] - 2026-06-24
+
+### Added
+
+- **Multi-recipient age encryption (EGB-283)** — a store-scoped, committed
+  `recipients.txt` (age `-R` format, with `# name` comment lines) lets one
+  store encrypt every blob to N age public keys — one per team member.
+  `secrets recipients add <age1…> [--name N]` adds a key and immediately
+  re-encrypts the whole store; `secrets recipients rm <key|name> [--yes]`
+  removes one and re-encrypts; `secrets recipients list` shows the current
+  set (or a note that the store is still single-key). A new `secrets
+  reencrypt` command re-encrypts every blob to the current recipients without
+  changing the set (idempotent heal / backfill after a manual edit). Absence
+  of `recipients.txt` preserves exact legacy single-key behavior; the first
+  `recipients add` on a legacy store bootstraps the file seeded with the
+  local pubkey plus the new key. `init` now seeds `recipients.txt` born-multi
+  with the freshly generated pubkey.
+
+### Changed
+
+- **`secrets rekey` on a multi-recipient store** no longer generates a new
+  keypair — instead it re-encrypts all blobs to the current `recipients.txt`
+  set (the shared `_reencrypt_all` engine). On a legacy store (no
+  `recipients.txt`) `rekey` keeps today's generate-new-keypair behavior.
+- **`secrets which`** now prints a `recipients: N (name, …)` line, or
+  `recipients: single-key (no recipients.txt)` for a legacy store.
+- **`secrets verify` / `verify --all`** assert that each blob's age
+  recipient-stanza count equals the number of entries in `recipients.txt`
+  (skipped on legacy stores). Exits non-zero on any count mismatch so it can
+  gate CI or a migration.
+
 ## [0.6.1.0] - 2026-06-08
 
 ### Changed
diff --git a/CLAUDE.md b/CLAUDE.md
index 176fd12..7fc4bb1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,7 +16,7 @@ cd ~/my-project && ./secrets pull # Pull + decrypt .env* files
 
 ```bash
 brew install bats-core
-bats test/          # runs secrets.bats + manifest.bats + migrate.bats
+bats test/          # runs secrets.bats + manifest.bats + migrate.bats + recipients.bats
 ./test/run-security.sh   # security regression subset + operator sign-off (see below)
 ```
 
@@ -56,7 +56,7 @@ skips security specialist + red team, and Step 11 skips adversarial review.
 
 ## Architecture
 
-Single bash script (`secrets`) with subcommands: init, push, pull, list, rm, rekey, verify, migrate.
+Single bash script (`secrets`) with subcommands: init, push, pull, list, rm, rekey, verify, migrate, recipients, reencrypt.
 
 - Encryption: `age` with key files (not passphrases — age passphrases are non-scriptable)
 - Storage: Private git repo at `~/.secrets/`
@@ -67,6 +67,24 @@ Single bash script (`secrets`) with subcommands: init, push, pull, list, rm, rek
 - External files: `.secrets-files` manifest tracks designated keys from files outside the project (e.g. `~/.gradle/gradle.properties`, merged not overwritten — EGB-531) and whole binary files (type `file`, e.g. an Android upload keystore — EGB-652); see below
 - Workspaces: `--workspaces` flag reads `package.json` workspaces, requires `jq`
 - Safety: Pre-commit hook rejects plaintext secret files (`.env`, `.dev.vars`, `gradle.properties`)
+- Multi-recipient (EGB-283): a store-scoped, committed `recipients.txt` (age `-R`
+  format, `# name` comments) lets one store encrypt every blob to N age keys —
+  one per team member. Managed via `secrets recipients add/rm/list`; absence of
+  the file ⇒ legacy single-key behavior (recipients = the pubkey derived from
+  `key.txt`). The file is parsed by us (never `age -R <path>`) into a validated
+  `RECIPIENT_ARGS` array (native age X25519 only, `age1[0-9a-z]{58}`; SSH
+  recipients rejected; symlinked file refused) — same conservative posture as
+  `.secrets-store`/`.secrets-files`. `_load_recipients` populates the array;
+  every encrypt site routes through it. Any recipient change re-encrypts the
+  WHOLE store in one commit via the shared `_reencrypt_all` engine (also used by
+  the new `secrets reencrypt` and by `rekey` on a multi-recipient store, where
+  rekey re-encrypts to the set with NO new keypair; legacy stores keep rekey's
+  generate-new-keypair behavior). `init` seeds `recipients.txt` born-multi.
+  `which` prints `recipients: N`; `verify`/`verify --all` assert each blob's
+  age recipient-stanza count equals `recipients.txt`'s length. Removal takes
+  effect going forward — git history stays readable by an old key, so rotate
+  genuinely-sensitive values. Decryption is unchanged (each member uses their
+  own `key.txt`).
 - Portability: must run on system bash 3.2 (macOS) — no associative arrays or bash-4 features
 
 ## Project Structure
@@ -77,7 +95,8 @@ hooks/pre-commit     # Pre-commit hook template
 test/
   secrets.bats       # bats-core test suite (133 tests)
   manifest.bats      # EGB-677 .secrets.json manifest tests (78 tests)
-  migrate.bats       # EGB-703 store-format-v2 migration tests (26 tests)
+  migrate.bats       # EGB-703 store-format-v2 migration tests (31 tests)
+  recipients.bats    # EGB-283 multi-recipient age encryption tests (30 tests)
   test_helper.bash   # Shared setup/teardown
 README.md            # User-facing documentation
 CLAUDE.md            # This file
diff --git a/README.md b/README.md
index ee177b3..2a1ddfa 100644
--- a/README.md
+++ b/README.md
@@ -129,13 +129,15 @@ secrets pull
 
 ### Sharing with teammates
 
-To share secrets with a teammate, they need:
+**Simple approach (shared key):** To share secrets with a teammate, they need:
 
 1. Access to your private `my-secrets` GitHub repo (add them as a collaborator)
 2. A copy of `key.txt` (send it to them directly — AirDrop, USB, or in-person)
 
 Everyone on the team uses the same key. When anyone runs `secrets push`, the encrypted files are updated and everyone else can `secrets pull` to get the latest version.
 
+**Per-teammate keys (recommended for teams):** Use `secrets recipients add` so each person keeps their own private key — no key sharing needed. See [Onboarding and offboarding teammates](#onboarding-and-offboarding-teammates) below.
+
 ## Usage
 
 ### Daily workflow
@@ -168,12 +170,16 @@ secrets clear
 | `secrets run <command>` | Pull secrets, run a command, then clear secrets when it exits |
 | `secrets list` | Show all projects that have stored secrets |
 | `secrets rm <project>` | Delete a project's secrets from the store |
-| `secrets rekey` | Generate a new encryption key and re-encrypt everything |
+| `secrets rekey` | Generate a new encryption key and re-encrypt everything (single-key store) or re-encrypt to the current recipients without changing keys (multi-recipient store) |
 | `secrets verify [project]` | Check the current project's `.secrets.json` against the store (missing/orphaned blobs) and decrypt every blob. `[project]` overrides the store directory name; the manifest is still read from the current directory |
 | `secrets verify --all` | Decrypt-test every blob in every project — a store-wide integrity sweep |
 | `secrets migrate [--dry-run]` | Copy-forward this project's encrypted blobs to store format v2 (non-destructive; manifest-free; `--dry-run` previews) |
 | `secrets migrate --status` | Survey every project's v2 readiness; exits non-zero until the whole store is finalize-ready |
 | `secrets migrate --finalize` | Drop the old v1 blobs and mark the store v2 — runs once, store-wide, after `verify` is green and every machine is upgraded |
+| `secrets recipients list` | List the store's recipient public keys (and names if set) |
+| `secrets recipients add <age1…> [--name N]` | Add a recipient key to the store and immediately re-encrypt every blob to the new set |
+| `secrets recipients rm <key\|name> [--yes]` | Remove a recipient and re-encrypt the store; `--yes` required when removing your own key |
+| `secrets reencrypt` | Re-encrypt every blob to the current recipients (idempotent — useful after a manual edit or partial failure) |
 
 ### Automatic project detection
 
@@ -448,6 +454,64 @@ Some external secrets are whole binary files — an Android upload keystore, a c
 
 On `secrets push` the file is encrypted into `<project>/external/`. On `secrets pull` it is restored to the same path with mode `600`; if a different version already exists there, it is backed up to `<name>.secrets-bak` first. The same path rules apply (inside `$HOME`, no `..`, no symlinks). Like merged Gradle keys, restored files are permanent plaintext on disk — `secrets clear` does not remove them.
 
+### Onboarding and offboarding teammates
+
+By default every team member uses the **same** `key.txt` (one shared private key). The multi-recipient feature lets each teammate have their **own** keypair while still sharing one store — so you never hand out a secret key to a new hire, and removing an ex-teammate's access is one command.
+
+#### Onboarding a teammate
+
+```bash
+# 1. Teammate generates their own keypair on their machine (never shares the private key)
+age-keygen -o ~/.secrets/key.txt          # writes key.txt; prints the public key
+
+# 2. Teammate sends you their PUBLIC key (printed by age-keygen, starts with age1…)
+#    — over Slack, email, whatever. Public keys are not secret.
+
+# 3. An existing member adds the public key to the store
+secrets recipients add age1theirpublickey --name alice
+# => Adds alice to recipients.txt, re-encrypts every blob to the full set, pushes.
+
+# 4. Teammate clones the store repo and drops their key.txt in place
+git clone git@github.com:<you>/my-secrets.git ~/.secrets
+# (key.txt already generated in step 1 — nothing to copy)
+
+# 5. Teammate pulls into any project
+cd ~/myapp
+secrets pull
+# => Their key matches one recipient stanza in every blob — it just works.
+```
+
+Run `secrets recipients list` to confirm who has access:
+
+```
+alice   age1theirpublickey…
+you     age1yourpublickey…
+```
+
+#### Offboarding a teammate
+
+```bash
+# Remove the recipient by name (or public key) and re-encrypt the store
+secrets recipients rm alice
+# => Removes alice from recipients.txt, re-encrypts every blob, pushes.
+# New blobs are no longer readable by alice's key.
+```
+
+> **Important:** git history can't be un-shared. If alice had access during a period when genuinely sensitive values were stored, rotate those values now (update them in the external system and run `secrets push`). The re-encrypt prevents future access; history is permanent.
+
+#### Managing recipients
+
+```bash
+secrets recipients list          # show all recipient keys and names
+secrets recipients add age1…     # add a key (bootstraps recipients.txt on a legacy store)
+secrets recipients add age1… --name bob   # attach a human-readable label
+secrets recipients rm bob        # remove by name
+secrets recipients rm age1…      # remove by public key
+secrets reencrypt                # re-encrypt to current recipients (idempotent heal)
+```
+
+`secrets which` shows a `recipients: N (alice, bob, …)` line so you can always confirm the active set from any project directory.
+
 ## Safety features
 
 - **`secrets run` auto-clears** — plaintext files are deleted when the command exits, errors, or is interrupted with Ctrl-C
@@ -501,7 +565,7 @@ For complete rotation with no historical exposure, create a fresh `~/.secrets/`
 ## Development
 
 ```bash
-# Run the test suite (237 tests across three files)
+# Run the test suite (272 tests across four files)
 brew install bats-core
 bats test/
 
diff --git a/VERSION b/VERSION
index 44e7f9a..e1e4873 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.6.1.0
+0.6.2.0
diff --git a/secrets b/secrets
index 421fc5f..e250d1b 100755
--- a/secrets
+++ b/secrets
@@ -2695,6 +2695,10 @@ Usage:
   secrets migrate [--dry-run]   Copy-forward this project's v1 blobs to store format v2
   secrets migrate --status      Survey every project's v2 readiness (finalize gate)
   secrets migrate --finalize    Drop v1 blobs and mark the store v2 (after verify)
+  secrets recipients list            List the store's recipient keys
+  secrets recipients add KEY [--name N]  Add a recipient and re-encrypt the store
+  secrets recipients rm KEY|NAME [--yes] Remove a recipient and re-encrypt the store
+  secrets reencrypt                  Re-encrypt every blob to the current recipients
   secrets which                 Show the active store, manifest, and external entries
   secrets where                 Alias for `which`
   secrets status                Alias for `which`

From 17772dfec651170c9f3794628a9180a5480295d9 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Wed, 24 Jun 2026 13:37:56 -0700
Subject: [PATCH 16/20] fix: validate-before-mutate in recipients add/rm +
 verify messaging + doc/UX polish (EGB-283)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix 1 (IMPORTANT): _recipients_rm and _recipients_add now call _load_recipients
  BEFORE any mutation. A hand-corrupted recipients.txt dies at validation, leaving
  the file untouched — prevents inconsistent state where the file is changed but
  blobs are not re-encrypted. On a legacy store (no recipients.txt), _load_recipients
  succeeds via the derived-pubkey path so the bootstrap path still works.

- Fix 2 (MINOR): Guard _check_blob_recipient_count behind a successful decrypt in
  both _verify_all and _verify_project — an undecryptable blob no longer produces a
  spurious "encrypted to 0 recipients" finding. Reword _verify_all summary to
  "failed (decrypt or recipient-count)" since both failure modes now increment the
  counter.

- Fix 3 (MINOR): Correct README offboarding comment from "New blobs are no longer
  readable" (contradicts the re-encrypt of EVERY blob) to "Existing blobs are
  re-encrypted; the removed key can no longer decrypt them."

- Fix 4 (MINOR): cmd_reencrypt prints an advisory when no recipients.txt exists
  (single-key store), so the operator knows they can add teammates.

- Fix 5 (MINOR): Test coverage for ambiguous-name rm refusing to remove when
  multiple recipients share a --name label.

Tests: 5 new tests in test/recipients.bats (34 total, all pass). Full suite
276 tests: 5 known pre-existing failures (3 mode-600/stat, 2 jq-PATH), none new.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md            |  2 +-
 secrets              | 40 ++++++++++++++++++++++++---------
 test/recipients.bats | 53 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 84 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 2a1ddfa..8f83d91 100644
--- a/README.md
+++ b/README.md
@@ -494,7 +494,7 @@ you     age1yourpublickey…
 # Remove the recipient by name (or public key) and re-encrypt the store
 secrets recipients rm alice
 # => Removes alice from recipients.txt, re-encrypts every blob, pushes.
-# New blobs are no longer readable by alice's key.
+# Existing blobs are re-encrypted; the removed key can no longer decrypt them.
 ```
 
 > **Important:** git history can't be un-shared. If alice had access during a period when genuinely sensitive values were stored, rotate those values now (update them in the external system and run `secrets push`). The re-encrypt prevents future access; history is permanent.
diff --git a/secrets b/secrets
index e250d1b..a66d90a 100755
--- a/secrets
+++ b/secrets
@@ -1854,6 +1854,9 @@ cmd_reencrypt() {
   resolve_store
   check_initialized
   check_key
+  if [ ! -e "$RECIPIENTS_FILE" ]; then
+    info "No $RECIPIENTS_FILE_NAME — single-key store; re-encrypting to your own key only. Add teammates with 'secrets recipients add'."
+  fi
   _load_recipients
   _reencrypt_all "reencrypt: re-encrypt all to current recipients"
 }
@@ -2128,6 +2131,11 @@ _recipients_add() {
   if [ -L "$RECIPIENTS_FILE" ]; then
     die "Refusing to write symlinked $RECIPIENTS_FILE_NAME."
   fi
+  # Validate BEFORE any mutation: a hand-corrupted file dies here, leaving
+  # recipients.txt untouched (no half-mutate / blobs-not-reencrypted skew).
+  # On a legacy store (no recipients.txt) _load_recipients succeeds via the
+  # derived-pubkey path and does NOT die — so the bootstrap path still works.
+  _load_recipients
   # Bootstrap a legacy store: seed this machine's key first so the operator
   # stays a recipient (and can decrypt to re-encrypt).
   if [ ! -e "$RECIPIENTS_FILE" ]; then
@@ -2172,6 +2180,9 @@ _recipients_rm() {
   [ -n "$target" ] || die "Usage: secrets recipients rm <age1...|name> [--yes]"
   [ -e "$RECIPIENTS_FILE" ] || die "No $RECIPIENTS_FILE_NAME — store is single-key; nothing to remove."
   [ -L "$RECIPIENTS_FILE" ] && die "Refusing to write symlinked $RECIPIENTS_FILE_NAME."
+  # Validate BEFORE any mutation: a hand-corrupted file dies here, leaving
+  # recipients.txt untouched (no half-mutate / blobs-not-reencrypted skew).
+  _load_recipients
   local k n match="" count=0 total=0
   while IFS=$'\t' read -r k n; do
     total=$((total + 1))
@@ -2319,9 +2330,12 @@ _verify_all() {
         rel="${f#"$SECRETS_DIR"/}"
         echo "FAIL: $rel does not decrypt with the current key." >&2
         failed=$((failed + 1))
-      fi
-      if ! _check_blob_recipient_count "$f" "${f#"$SECRETS_DIR"/}" "$rexpected"; then
-        failed=$((failed + 1))
+      else
+        # Only check recipient count when the blob actually decrypted — an
+        # undecryptable blob would report "0 recipients" which is spurious.
+        if ! _check_blob_recipient_count "$f" "${f#"$SECRETS_DIR"/}" "$rexpected"; then
+          failed=$((failed + 1))
+        fi
       fi
     done < <(find "$dir" -type f -name '*.age')
   done
@@ -2330,7 +2344,7 @@ _verify_all() {
     return 0
   fi
   if [ "$failed" -gt 0 ]; then
-    echo "verify --all: $failed of $checked blob(s) failed to decrypt." >&2
+    echo "verify --all: $failed of $checked blob(s) failed (decrypt or recipient-count)." >&2
     return 1
   fi
   info "verify --all: OK — all $checked blob(s) decrypt with the current key (integrity only; run 'secrets verify' in a project for manifest consistency)."
@@ -2389,9 +2403,12 @@ _verify_project() {
     if ! _verify_blob_decrypts "$blob"; then
       echo "FINDING: blob for '$rel' ($project/$rel.age) does not decrypt with the current key." >&2
       findings=$((findings + 1))
-    fi
-    if ! _check_blob_recipient_count "$blob" "$project/$rel.age" "$rexpected"; then
-      findings=$((findings + 1))
+    else
+      # Only check recipient count when the blob actually decrypted — an
+      # undecryptable blob would report "0 recipients" which is spurious.
+      if ! _check_blob_recipient_count "$blob" "$project/$rel.age" "$rexpected"; then
+        findings=$((findings + 1))
+      fi
     fi
   done < <(jq -r '.dotenv // [] | .[]' "$manifest")
 
@@ -2418,9 +2435,12 @@ _verify_project() {
     if ! _verify_blob_decrypts "$eblob"; then
       echo "FINDING: external blob for '$epath' ($project/$erel) does not decrypt with the current key." >&2
       findings=$((findings + 1))
-    fi
-    if ! _check_blob_recipient_count "$eblob" "$project/$erel" "$rexpected"; then
-      findings=$((findings + 1))
+    else
+      # Only check recipient count when the blob actually decrypted — an
+      # undecryptable blob would report "0 recipients" which is spurious.
+      if ! _check_blob_recipient_count "$eblob" "$project/$erel" "$rexpected"; then
+        findings=$((findings + 1))
+      fi
     fi
   done < <(_json_external_entries "$manifest")
 
diff --git a/test/recipients.bats b/test/recipients.bats
index 4c11199..1ed71af 100644
--- a/test/recipients.bats
+++ b/test/recipients.bats
@@ -341,6 +341,59 @@ make_second_identity() {
   [[ "$output" == *"valid age recipient"* ]] || false
 }
 
+# ── Fix 1: validate-before-mutate ────────────────────────────────────────────
+
+@test "recipients rm dies without mutating a hand-corrupted recipients.txt" {
+  init_with_remote
+  make_second_identity
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob   # valid: self + bob
+  # Corrupt the file by hand.
+  printf 'age1-not-a-valid-key\n' >> "$SECRETS_DIR/recipients.txt"
+  before=$(cat "$SECRETS_DIR/recipients.txt")
+  run "$SECRETS_BIN" recipients rm bob
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid recipient"* ]] || false
+  # File unchanged (no half-mutation).
+  [ "$(cat "$SECRETS_DIR/recipients.txt")" = "$before" ]
+}
+
+@test "recipients add dies without mutating a hand-corrupted recipients.txt" {
+  init_with_remote
+  make_second_identity
+  printf 'age1-not-a-valid-key\n' >> "$SECRETS_DIR/recipients.txt"   # init seeded self; now corrupt
+  before=$(cat "$SECRETS_DIR/recipients.txt")
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name bob
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Invalid recipient"* ]] || false
+  [ "$(cat "$SECRETS_DIR/recipients.txt")" = "$before" ]
+}
+
+# ── Fix 4: reencrypt advisory on a legacy store ───────────────────────────────
+
+@test "reencrypt on a legacy store prints a single-key advisory" {
+  init_with_remote
+  rm -f "$SECRETS_DIR/recipients.txt"
+  create_project_dir myproj
+  run "$SECRETS_BIN" push
+  run "$SECRETS_BIN" reencrypt
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"single-key"* ]] || false
+}
+
+# ── Fix 5: ambiguous-name rm coverage ────────────────────────────────────────
+
+@test "recipients rm by an ambiguous name is refused" {
+  init_with_remote
+  make_second_identity
+  age-keygen -o "$TEST_TMPDIR/carol.txt" 2>/dev/null
+  CAROL_PUB=$(age-keygen -y "$TEST_TMPDIR/carol.txt")
+  run "$SECRETS_BIN" recipients add "$BOB_PUB" --name dup
+  run "$SECRETS_BIN" recipients add "$CAROL_PUB" --name dup
+  run "$SECRETS_BIN" recipients rm dup
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"matches"* ]] || false
+}
+
 @test "SECURITY: a symlinked recipients.txt is refused on add and rm too" {
   init_with_remote
   make_second_identity

From dd6a025fa05bb45061f680151fc373c9b8379209 Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Tue, 8 Sep 2026 14:20:20 -0700
Subject: [PATCH 17/20] fix: surface store sync failures + add `secrets sync`
 (EGB-1230, EGB-1231)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EGB-1230: `cmd_pull` synced the store with `git pull >/dev/null 2>&1` under
`set -euo pipefail`. A store that couldn't fast-forward killed the script at
that line with git's exit 128 and nothing on stdout or stderr — a banner, no
restored files, no reason, and invisible in a pipeline. The sync now routes
through `_store_sync_pull`, which guards the pull, captures git's output as
the diagnosis, and dies naming the store path and `secrets sync`. It is now
`--ff-only` to match the push path, so a plain pull can no longer manufacture
a merge commit in the store.

EGB-1231: once a store diverged there was no way out — push demanded a
fast-forward and pointed at pull, which couldn't fast-forward either, so the
advice looped and recovery meant hand-running git next to encrypted blobs.
Adds `secrets sync`: fetch, stash, rebase onto the remote, restore the stash,
then a confirmation-gated push of local commits (`--yes` to skip the prompt,
`--dry-run` to report only). Non-destructive by construction — no merge, no
force-push, no `reset --hard`, no `stash drop`; a rebase conflict names the
conflicting files and leaves the store exactly as found. `secrets which` gains
a `remote:` line reporting ahead/behind/dirty, and push's dead-end message now
points at `sync`.

test/sync.bats: 25 new tests. Full suite 353/353 green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrUoYuUMoTj91rzV4vxGPB
---
 CHANGELOG.md   |  41 ++++++
 CLAUDE.md      |   4 +-
 README.md      |  29 ++++
 VERSION        |   2 +-
 secrets        | 240 ++++++++++++++++++++++++++++++-
 test/sync.bats | 373 +++++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 681 insertions(+), 8 deletions(-)
 create mode 100644 test/sync.bats

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d37cd05..7e7cde1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to a four-digit MAJOR.MINOR.PATCH.MICRO version scheme.
 
+## [0.7.6.0] - 2026-09-08
+
+### Added
+
+- **`secrets sync` — reconcile a diverged store (EGB-1231)** — the store is a
+  git repo, and once a clone was both ahead and behind its remote the CLI had
+  no way out: `push` demanded a fast-forward and pointed at `pull`, which
+  could not fast-forward either, so the advice looped and recovery meant
+  hand-running git next to a directory of encrypted blobs. `secrets sync`
+  fetches, stashes uncommitted blob edits, rebases local commits onto the
+  remote, restores the stash, and then asks before publishing local commits to
+  the shared store. `--yes` skips the prompt (scripts/CI); `--dry-run` reports
+  ahead/behind/dirty and what would happen, changing nothing. Deliberately
+  non-destructive: no merge, no force-push, no `reset --hard`, no `stash
+  drop`. A rebase conflict aborts, restores the stash, names the conflicting
+  files, and leaves the store exactly as found.
+- **Store state in `secrets which` (EGB-1231)** — a new `remote:` line reports
+  the store's `ahead N, behind N, N modified` (or `up to date`) against its
+  upstream, with a `(run: secrets sync)` hint when there is anything to
+  reconcile. Offline-safe (reports against the last fetch, never reaches the
+  network) and silent for a local-only store or one with no upstream.
+
+### Fixed
+
+- **`secrets pull` no longer fails silently when the store can't sync
+  (EGB-1230)** — the store sync was `git pull >/dev/null 2>&1` under `set -euo
+  pipefail`, so a store that could not fast-forward killed the script at that
+  line with git's exit 128 and *nothing* on stdout or stderr. The user saw a
+  banner, no restored files, and no reason — indistinguishable from a project
+  with nothing to pull, and easy to lose entirely in a pipeline. The sync is
+  now guarded, git's output is captured and surfaced as the diagnosis, and the
+  error names the store path and points at `secrets sync`.
+
+### Changed
+
+- **`secrets pull`'s store sync is now fast-forward only**, matching the push
+  path. A plain `git pull` could quietly manufacture a merge commit in the
+  store; divergence is now resolved in exactly one place — `secrets sync`.
+- **The push path's dead-end advice** ("Run 'secrets pull' first, then retry
+  push") now points at `secrets sync` and includes git's own output.
+
 ## [0.7.5.0] - 2026-06-24
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index a7afbda..8bfe715 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -56,13 +56,14 @@ skips security specialist + red team, and Step 11 skips adversarial review.
 
 ## Architecture
 
-Single bash script (`secrets`) with subcommands: init, push, pull, list, rm, rekey, verify, migrate, recipients, reencrypt, upgrade.
+Single bash script (`secrets`) with subcommands: init, push, pull, list, rm, rekey, verify, migrate, recipients, reencrypt, sync, upgrade.
 
 - Encryption: `age` with key files (not passphrases — age passphrases are non-scriptable)
 - Storage: Private git repo at `~/.secrets/`
 - Convention: Tracks `.env`, `.env.*`, and `.dev.vars` (not `.envrc`, `.environment-*`)
 - Manifest (EGB-677 stage 1): committed `.secrets.json` is the source of truth for what syncs — `dotenv[]` (project-relative, nested ok, `@` allowed; rail rejects `..`/absolute/symlink) + `external[]` (`properties`/`file`). Push discovery auto-adds (gated by committed `options.autoAdd`, default ON; `--frozen`/`--dry-run` overrides), bootstraps the manifest on first push (written only after ≥1 blob encrypts), and absorbs a legacy `.secrets-files` (gradle-properties → `properties`; on pull the legacy file is superseded with a warning). Store layout: nested dotenv entries land at `<project>/<relpath>.age` (relpath preserved — the store self-describes where a file restores). jq is a hard dep only when a manifest exists/is written; manifest-less projects run jq-free (manifest features skipped with a notice). `check_cmd` prints platform-aware install hints.
 - Store format (EGB-677 stage 2 / EGB-703): the store is self-describing via a committed one-line `$SECRETS_DIR/.secrets-format` file (`2`). Absence ⇒ v1 (every store predating EGB-703). v2's only on-disk change vs v1 is the external `properties` blob suffix: `.gradle-properties.age` → `.properties.age` (matching the manifest `type`); dotenv and `file` blobs are unchanged. `_store_format()` reads the marker. **Additive v2 (EGB-712):** reads resolve a `properties` blob by trying `.properties.age` then falling back to `.gradle-properties.age` (`_resolve_external_blob_read`); writes dual-write a `properties` external only when a v1 twin already exists in the store (`_external_blob_write_targets`), so existing externals keep old clients fresh while brand-new externals are written v2-only (a gentle forcing function). Blob location no longer depends on the marker — the old `_external_blob_suffix` is gone. `init` stamps a fresh store v2 (born-v2). `secrets which` prints the store-format line `format: vN`, and (EGB-700) when a `.secrets.json` is present the manifest header line also carries its schema version (`manifest (.secrets.json at <path>, version N):`). **Migration is copy-forward and non-destructive:** `secrets migrate --dry-run` (per project, reports old→new, writes nothing) → `secrets migrate` (per project, manifest-free: enumerates the store's `*.gradle-properties.age` blobs directly — same source of truth as `--finalize` — and writes their `.properties.age` twins, so a legacy `.secrets-files`-only project with no `.secrets.json` migrates cleanly and no store blob is left un-twinned; idempotent; EGB-710) → `secrets migrate --finalize` (store-wide; the ONLY destructive step — gates on `verify --all` green + every v1 blob having a v2 twin, cuts a `pre-v2-migrate-<sha>` recovery tag, stamps the marker, then drops v1 blobs; refuses without `--yes`/operator confirmation since a lagging v1 client against a finalized store stops seeing `properties` externals until it upgrades). `secrets migrate --status` is a read-only survey that walks every project in the store and reports each one's v2 readiness (v2-ready / migrated / NEEDS MIGRATE, plus a `v2-only` count of externals old clients can't read), exiting non-zero while any v1 blob is un-twinned so it gates the path to `--finalize` (EGB-710/EGB-712). **Under additive v2 (EGB-712) `--finalize` is now OPTIONAL GC, not a required milestone:** because upgraded clients dual-write existing externals and read-fall-back, *not* finalizing never cuts anyone off — finalize only reclaims the duplicate v1 blobs and stays deferrable indefinitely (defusing the cross-machine coordination gate). dotenv and `file` blobs are identical across formats, so they always propagate to old clients; only a brand-new `properties` external is v2-only. **Version-skew nudge (EGB-713):** a committed `$SECRETS_DIR/.secrets-writer-version` records the highest client `VERSION` that has written to the store (monotonic; stamped via `_stamp_writer_version` right before each store-committing `git add -A` — push/rekey/migrate/finalize — never on read paths, so it always rides a commit and never dangles to break `pull --ff-only`). `check_initialized` calls `_check_store_version_skew`, which warns once per invocation (stderr, non-fatal, `set -e`-safe) when the store's stamp is numerically greater than `_client_version` (read from `$SCRIPT_DIR/VERSION`); `secrets which` prints the `written-by:` line. Stores with no stamp (pre-EGB-713) are silent. The deliberate flatten-to-basename naming the EGB-677 CEO plan sketched was dropped as lossy (it discards the restore relpath that makes the store self-describing) — see the EGB-703 eureka. **Upgrade verb (EGB-716):** `secrets upgrade` is the fix path paired with the EGB-713 skew *warning* — it `git -C "$SCRIPT_DIR" pull --ff-only`s the tool's own checkout (fast-forward only, never merges/rewrites local commits), reports `vOLD -> vNEW`, then best-effort re-checks `_store_writer_version` against the new on-disk version so the operator sees whether the nudge is cleared (the new code takes effect next invocation). `secrets upgrade --check` does `git fetch` + `rev-list --count HEAD..@{u}` and reports availability without pulling. Deliberately thin: no auto-update, no background polling (security tool). Directed errors for not-a-git-checkout / no-upstream / diverged / offline. `cmd_upgrade` never calls `check_initialized` (it's about the tool, not the store); the skew re-check is silent unless a store with a writer-version resolves.
+- Store sync + divergence (EGB-1230/EGB-1231): the store is a git repo, so a clone can end up ahead of and behind its remote at once. **EGB-1230:** `cmd_pull`'s sync used to be `git pull >/dev/null 2>&1` under `set -euo pipefail` — a store that couldn't fast-forward killed the script there with git's exit 128 and nothing on either stream (a banner, no files, no reason; invisible in a pipeline). It now routes through `_store_sync_pull`, which guards the pull, captures git's output as the diagnosis, and dies naming the store path and `secrets sync`. That sync is **`--ff-only`**, matching the push path — a plain `git pull` could quietly manufacture a merge commit in the store, and divergence is now resolved in exactly one place. **EGB-1231:** `_store_git_state` emits `ahead\tbehind\tdirty` (from `rev-list --left-right --count @{u}...HEAD` plus `status --porcelain`) and `_format_store_state` renders it; `cmd_which` prints a `remote:` line from them — offline-safe (reports against the last fetch), silent with no remote/upstream. `cmd_sync` is the reconcile verb the CLI was missing: fetch → report state → stash (`push -u`) → `rebase @{u}` → restore stash → `ensure_store_protections` (rebased-in history may lack `.gitignore`, and a store missing the `key.txt` line would stage the private key — same reasoning as push) → **confirmation-gated** `git push` of local commits. The gate (`_sync_confirm_push`) reads `/dev/tty` and requires a tty, so it stays CLOSED in scripts/CI rather than publishing to a shared store by default; `--yes` opens it, `--dry-run` reports and returns before any mutation. Non-destructive by construction: no merge, no `--force`, no `reset --hard`, no `stash drop`. A rebase conflict collects the conflicting paths BEFORE `rebase --abort` (the abort clears them), restores the stash, and dies — store byte-identical to how it was found. `_sync_restore_stash` never drops the stash on a failed pop; it tells the operator where their only copy lives. `cmd_sync` does not `_stamp_writer_version`: it replays existing commits rather than authoring content, and the stamp is specified to ride a store-committing `git add -A`. Test suite: `test/sync.bats` (25 tests), including a grep over the `cmd_sync` body asserting the destructive git verbs never appear in it.
 - Verify (EGB-698): `secrets verify` is a read-only integrity check. Default mode (current project) cross-checks `$PWD/.secrets.json` against `$SECRETS_DIR/<project>/` both ways (declared-but-missing blobs + orphaned blobs) and decrypt-tests every blob (dotenv + external) by streaming plaintext to `/dev/null` (never written to disk). `secrets verify --all` decrypt-tests every blob in every project (integrity only — the store carries no manifests, so consistency can't be checked store-wide). Both recurse the whole project tree (`find -type f`, same as rekey/list). Exits non-zero on any finding so it can gate the stage-2 `migrate --finalize` and CI. The store deliberately holds no manifest — `.secrets.json` is committed in each project's own repo and read from `$PWD`.
 - External files: `.secrets-files` manifest tracks designated keys from files outside the project (e.g. `~/.gradle/gradle.properties`, merged not overwritten — EGB-531) and whole binary files (type `file`, e.g. an Android upload keystore — EGB-652); see below
 - Workspaces: `--workspaces` flag reads `package.json` workspaces, requires `jq`
@@ -97,6 +98,7 @@ test/
   manifest.bats      # EGB-677 .secrets.json manifest tests (83 tests)
   migrate.bats       # EGB-703 store-format-v2 migration tests (35 tests)
   upgrade.bats       # EGB-716 `secrets upgrade` self-update tests (8 tests)
+  sync.bats          # EGB-1230/1231 store sync + divergence reconcile tests (25 tests)
   recipients.bats    # EGB-283 multi-recipient age encryption tests (34 tests)
   test_helper.bash   # Shared setup/teardown
 README.md            # User-facing documentation
diff --git a/README.md b/README.md
index 4ebb17b..f838ad5 100644
--- a/README.md
+++ b/README.md
@@ -193,6 +193,9 @@ secrets clear
 | `secrets recipients add <age1…> [--name N]` | Add a recipient key to the store and immediately re-encrypt every blob to the new set |
 | `secrets recipients rm <key\|name> [--yes]` | Remove a recipient and re-encrypt the store; `--yes` required when removing your own key |
 | `secrets reencrypt` | Re-encrypt every blob to the current recipients (idempotent — useful after a manual edit or partial failure) |
+| `secrets sync` | Reconcile a store that has diverged from its remote: stash local blob edits, rebase onto the remote, restore the stash, then offer to publish your local commits. Never merges, force-pushes, or hard-resets |
+| `secrets sync --dry-run` | Report the store's ahead/behind/dirty state and what a reconcile would do; changes nothing |
+| `secrets sync --yes` | Reconcile and publish local commits without the confirmation prompt (for scripts) |
 | `secrets upgrade` | Self-update the tool: `git pull --ff-only` on the `secrets` checkout, report old → new version, then re-check store version-skew. No auto-update, no background checks |
 | `secrets upgrade --check` | Report whether an update is available (without pulling); changes nothing |
 
@@ -211,6 +214,32 @@ Store-format v2 is **additive** — an upgraded client reads either blob suffix
 
 And you'll be told when you're behind: if a store was last written by a newer `secrets` than the one you're running, any command prints a one-line nudge to stderr (non-fatal) — and `secrets which` shows the store's `written-by:` version. Stores written by older builds (no version stamp) stay silent.
 
+### When the store diverges
+
+The store is a git repo, so two machines pushing at once can leave your clone
+both ahead and behind its remote. `secrets push` needs a fast-forward and
+`secrets pull` won't silently merge, so both stop and tell you to run:
+
+```bash
+secrets sync
+```
+
+`sync` fetches, stashes any uncommitted blob edits, rebases your local commits
+onto the remote, restores the stash, and then *asks* before publishing your
+commits to the shared store (`--yes` skips the prompt; `--dry-run` just
+reports). If the rebase conflicts, it aborts, restores your stash, names the
+conflicting files, and leaves the store exactly as it found it — nothing in
+the path force-pushes, hard-resets, or drops a stash.
+
+`secrets which` now reports the same state up front, so you can see it coming:
+
+```
+store:  /Users/you/.secrets
+source: default
+format: v2
+remote: ahead 1, behind 11, 3 modified  (run: secrets sync)
+```
+
 ### Automatic project detection
 
 When you run `secrets push` or `secrets pull` without specifying a project name, the tool figures out which project you're in by:
diff --git a/VERSION b/VERSION
index e413a4a..29e2792 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.7.5.0
+0.7.6.0
diff --git a/secrets b/secrets
index da8f4be..8d947dc 100755
--- a/secrets
+++ b/secrets
@@ -1339,6 +1339,65 @@ ensure_store_protections() {
   fi
 }
 
+# ─── Store git state (EGB-1230 / EGB-1231) ─────────────────────────────
+
+# True when the store has an 'origin' remote. Everything below is a no-op
+# without one — a local-only store can never be out of sync with anything.
+_store_has_remote() {
+  git -C "$SECRETS_DIR" remote get-url origin >/dev/null 2>&1
+}
+
+# Emit "<ahead>\t<behind>\t<dirty>" for the store against its upstream.
+# Reads only what git already knows — the caller decides whether to fetch
+# first, so `which` stays cheap and offline-safe while `sync` sees fresh
+# counts. Returns 1 (emitting nothing) when there is no upstream to compare
+# against, which is the normal state for a local-only store.
+_store_git_state() {
+  _store_has_remote || return 1
+  git -C "$SECRETS_DIR" rev-parse --abbrev-ref '@{u}' >/dev/null 2>&1 || return 1
+  local counts ahead behind dirty
+  # --left-right --count prints "<behind>\t<ahead>" for @{u}...HEAD.
+  counts=$(git -C "$SECRETS_DIR" rev-list --left-right --count '@{u}...HEAD' 2>/dev/null) || return 1
+  behind=$(printf '%s' "$counts" | awk '{print $1}')
+  ahead=$(printf '%s' "$counts" | awk '{print $2}')
+  dirty=$(git -C "$SECRETS_DIR" status --porcelain 2>/dev/null | grep -c . || true)
+  # `grep -c` on empty input exits 1 under `set -e`; normalize to a number.
+  [ -n "$dirty" ] || dirty=0
+  printf '%s\t%s\t%s\n' "${ahead:-0}" "${behind:-0}" "$dirty"
+}
+
+# Render a state triple as one human line: "ahead 1, behind 11, 3 modified",
+# or "up to date" when there is genuinely nothing to reconcile.
+_format_store_state() {
+  local ahead="$1" behind="$2" dirty="$3" parts=""
+  [ "$ahead" -gt 0 ] 2>/dev/null && parts="ahead $ahead"
+  [ "$behind" -gt 0 ] 2>/dev/null && parts="${parts:+$parts, }behind $behind"
+  [ "$dirty" -gt 0 ] 2>/dev/null && parts="${parts:+$parts, }$dirty modified"
+  printf '%s' "${parts:-up to date}"
+}
+
+# Sync the store from its remote before reading or writing blobs.
+#
+# EGB-1230: this used to be `git pull >/dev/null 2>&1` under `set -euo
+# pipefail`, so a store that could not fast-forward killed the script at
+# that line with git's exit 128 and NOTHING on either stream — the user saw
+# a banner, no files, and no reason. git's output is the diagnosis; capture
+# it and put it in the error.
+#
+# Fast-forward only, matching the push path: a plain `git pull` can quietly
+# manufacture a merge commit in the store. Divergence gets resolved in
+# exactly one place — `secrets sync`.
+_store_sync_pull() {
+  _store_has_remote || return 0
+  local out
+  if ! out=$(git -C "$SECRETS_DIR" pull --ff-only 2>&1); then
+    die "Store sync failed ($SECRETS_DIR):
+$(printf '%s\n' "$out" | sed 's/^/  /')
+The store has diverged from its remote or has local changes.
+Run: secrets sync"
+  fi
+}
+
 # ─── Subcommands ───────────────────────────────────────────────────────
 
 cmd_init() {
@@ -1595,8 +1654,14 @@ commit_and_push_secrets() {
   local message="$1"
 
   if git -C "$SECRETS_DIR" remote get-url origin >/dev/null 2>&1; then
-    if ! git -C "$SECRETS_DIR" pull --ff-only 2>/dev/null; then
-      die "Fast-forward pull failed. Run 'secrets pull' first, then retry push."
+    # EGB-1231: this used to point at `secrets pull`, which cannot resolve a
+    # diverged store either — the advice looped. `secrets sync` is the one
+    # command that reconciles.
+    local ff_out
+    if ! ff_out=$(git -C "$SECRETS_DIR" pull --ff-only 2>&1); then
+      die "Store sync failed ($SECRETS_DIR):
+$(printf '%s\n' "$ff_out" | sed 's/^/  /')
+Run 'secrets sync' to reconcile, then retry push."
     fi
   fi
 
@@ -1865,10 +1930,8 @@ cmd_pull() {
   info "Pulling secrets for project: $project"
   echo_store_if_non_default
 
-  # Pull latest
-  if git -C "$SECRETS_DIR" remote get-url origin >/dev/null 2>&1; then
-    git -C "$SECRETS_DIR" pull >/dev/null 2>&1
-  fi
+  # Pull latest. Guarded and unsilenced — see _store_sync_pull (EGB-1230).
+  _store_sync_pull
 
   # ── Manifest-driven pull (EGB-677 stage 1) ──
   # With a .secrets.json present, the manifest decides what restores and
@@ -2621,6 +2684,19 @@ cmd_which() {
   # EGB-700 (folded into EGB-703): surface the store format so users can tell
   # v1 from v2 during the migration window. v1 = legacy store, no format marker.
   echo "format: v$(_store_format)"
+  # EGB-1231: the one thing `which` never reported was the thing that
+  # actually blocks push and pull — whether the clone is ahead/behind/dirty
+  # relative to its remote. Offline-safe: reports against the last fetch,
+  # never reaches the network, and stays silent for a local-only store.
+  local _st _a _b _d
+  if _st=$(_store_git_state); then
+    IFS=$'\t' read -r _a _b _d <<< "$_st"
+    if [ "$_a" -gt 0 ] || [ "$_b" -gt 0 ] || [ "$_d" -gt 0 ]; then
+      echo "remote: $(_format_store_state "$_a" "$_b" "$_d")  (run: secrets sync)"
+    else
+      echo "remote: $(_format_store_state "$_a" "$_b" "$_d")"
+    fi
+  fi
   local _wv; _wv=$(_store_writer_version)
   if [ -n "$_wv" ]; then
     local _cv; _cv=$(_client_version)
@@ -2703,6 +2779,154 @@ cmd_which() {
 # After a real update it best-effort re-checks the store's writer-version skew
 # against the NEW on-disk version, so the operator sees whether the EGB-713
 # nudge is now cleared (the new code itself takes effect on the next command).
+# Put a stashed working tree back. Never drops the stash on failure — the
+# entry is the only copy of the operator's uncommitted blob edits.
+_sync_restore_stash() {
+  [ "$1" = true ] || return 0
+  local out
+  if out=$(git -C "$SECRETS_DIR" stash pop 2>&1); then
+    info "Restored your local store changes."
+    return 0
+  fi
+  echo "WARNING: could not restore your stashed store changes:" >&2
+  printf '%s\n' "$out" | sed 's/^/  /' >&2
+  echo "They are SAFE and still stashed. Inspect with:" >&2
+  echo "  git -C \"$SECRETS_DIR\" stash list" >&2
+  echo "  git -C \"$SECRETS_DIR\" stash show -p" >&2
+  return 1
+}
+
+# The push gate (EGB-1231): publishing local commits to a store other people
+# pull from is an outward-facing act, so it needs an explicit yes. No tty
+# means no confirmation — the gate stays closed rather than opening by
+# default in scripts and CI.
+_sync_confirm_push() {
+  [ -t 0 ] && [ -e /dev/tty ] || return 1
+  printf "Publish %s local commit(s) to the shared store? [y/N] " "$1" > /dev/tty 2>/dev/null || return 1
+  local ans=""
+  read -r ans < /dev/tty 2>/dev/null || return 1
+  case "$ans" in [Yy]*) return 0 ;; *) return 1 ;; esac
+}
+
+# EGB-1231: reconcile a store that has diverged from its remote.
+#
+# This is the command that was missing. Before it, `push` demanded a
+# fast-forward and told you to run `pull`, and `pull` could not fast-forward
+# either — the advice looped and the only way out was hand-running git next
+# to a directory of encrypted blobs, which is where someone reaches for
+# `reset --hard` and destroys the local work.
+#
+# Deliberately non-destructive: stash (never drop), rebase (never merge,
+# never force), abort-and-restore on any conflict. Every failure path leaves
+# the store exactly as it was found.
+cmd_sync() {
+  check_cmd git
+  resolve_store
+  check_initialized
+
+  local dry_run=false assume_yes=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --dry-run|-n) dry_run=true; shift ;;
+      --yes|-y)     assume_yes=true; shift ;;
+      -*) die "Unknown sync flag: $1. Usage: secrets sync [--dry-run] [--yes]" ;;
+      *)  die "secrets sync takes no arguments (got: $1)" ;;
+    esac
+  done
+
+  if ! _store_has_remote; then
+    die "Store has no remote configured — nothing to reconcile ($SECRETS_DIR).
+Wire one with: git -C \"$SECRETS_DIR\" remote add origin <url>"
+  fi
+
+  info "Reconciling store: $SECRETS_DIR"
+
+  local out
+  if ! out=$(git -C "$SECRETS_DIR" fetch origin 2>&1); then
+    die "Fetch failed ($SECRETS_DIR):
+$(printf '%s\n' "$out" | sed 's/^/  /')"
+  fi
+
+  local st ahead behind dirty
+  if ! st=$(_store_git_state); then
+    die "The store's branch has no upstream to reconcile against ($SECRETS_DIR).
+Set one with: git -C \"$SECRETS_DIR\" branch --set-upstream-to origin/<branch>"
+  fi
+  IFS=$'\t' read -r ahead behind dirty <<< "$st"
+  echo "  state: $(_format_store_state "$ahead" "$behind" "$dirty")"
+
+  if [ "$dry_run" = true ]; then
+    if [ "$behind" -gt 0 ]; then
+      echo "  would: rebase $ahead local commit(s) onto origin ($behind to integrate)"
+    elif [ "$ahead" -gt 0 ]; then
+      echo "  would: publish $ahead local commit(s)"
+    fi
+    [ "$dirty" -gt 0 ] && echo "  would: stash and restore $dirty uncommitted change(s)"
+    info "Dry run — nothing changed."
+    return 0
+  fi
+
+  if [ "$ahead" -eq 0 ] && [ "$behind" -eq 0 ]; then
+    info "Nothing to reconcile."
+    return 0
+  fi
+
+  # Stash before touching history: a rebase refuses to start on a dirty tree,
+  # and those uncommitted .age edits may be the only copy of a secret.
+  local stashed=false
+  if [ "$dirty" -gt 0 ]; then
+    if ! out=$(git -C "$SECRETS_DIR" stash push -u -m "secrets sync" 2>&1); then
+      die "Could not stash local store changes ($SECRETS_DIR):
+$(printf '%s\n' "$out" | sed 's/^/  /')"
+    fi
+    stashed=true
+    info "Stashed $dirty uncommitted change(s)."
+  fi
+
+  if [ "$behind" -gt 0 ]; then
+    if ! out=$(git -C "$SECRETS_DIR" rebase '@{u}' 2>&1); then
+      # Collect the conflicting paths BEFORE aborting — the abort clears them.
+      local conflicts
+      conflicts=$(git -C "$SECRETS_DIR" diff --name-only --diff-filter=U 2>/dev/null || true)
+      git -C "$SECRETS_DIR" rebase --abort >/dev/null 2>&1 || true
+      _sync_restore_stash "$stashed" || true
+      die "Store reconcile hit a conflict — the store is unchanged.
+Conflicting files:
+$(printf '%s\n' "${conflicts:-(see git output below)}" | sed 's/^/  /')
+$(printf '%s\n' "$out" | sed 's/^/  /')
+Resolve by hand in $SECRETS_DIR, or ask the other machine to push again."
+    fi
+    info "Rebased onto origin."
+  fi
+
+  _sync_restore_stash "$stashed" || true
+
+  # Same reasoning as the push path: rebased-in history may lack .gitignore,
+  # and a store missing the key.txt line would stage the private key.
+  ensure_store_protections
+
+  # Re-read state — the rebase changed it.
+  st=$(_store_git_state) || st=$'0\t0\t0'
+  IFS=$'\t' read -r ahead behind dirty <<< "$st"
+
+  if [ "$ahead" -gt 0 ]; then
+    if [ "$assume_yes" != true ] && ! _sync_confirm_push "$ahead"; then
+      info "Reconciled locally. $ahead local commit(s) NOT published."
+      echo "  Publish them with: secrets sync --yes"
+      return 0
+    fi
+    if ! out=$(git -C "$SECRETS_DIR" push 2>&1); then
+      die "Push failed ($SECRETS_DIR):
+$(printf '%s\n' "$out" | sed 's/^/  /')"
+    fi
+    info "Published $ahead local commit(s)."
+  fi
+
+  st=$(_store_git_state) || st=$'0\t0\t0'
+  IFS=$'\t' read -r ahead behind dirty <<< "$st"
+  info "Store reconciled: $(_format_store_state "$ahead" "$behind" "$dirty")"
+}
+
 cmd_upgrade() {
   local check_only=0
   while [ $# -gt 0 ]; do
@@ -3243,6 +3467,9 @@ Usage:
   secrets recipients add KEY [--name N]  Add a recipient and re-encrypt the store
   secrets recipients rm KEY|NAME [--yes] Remove a recipient and re-encrypt the store
   secrets reencrypt                  Re-encrypt every blob to the current recipients
+  secrets sync                  Reconcile a diverged store with its remote
+  secrets sync --dry-run        Report ahead/behind/dirty; change nothing
+  secrets sync --yes            Reconcile and publish local commits without prompting
   secrets which                 Show the active store, manifest, and external entries
   secrets where                 Alias for `which`
   secrets status                Alias for `which`
@@ -3419,6 +3646,7 @@ case "${1:-help}" in
   migrate) shift; cmd_migrate "$@" ;;
   recipients) shift; cmd_recipients "$@" ;;
   which|where|status) cmd_which ;;
+  sync)    shift; cmd_sync "$@" ;;
   upgrade) shift; cmd_upgrade "$@" ;;
   help|--help|-h) cmd_help ;;
   *)      die "Unknown command: $1. Run 'secrets help' for usage." ;;
diff --git a/test/sync.bats b/test/sync.bats
new file mode 100644
index 0000000..3cc90e8
--- /dev/null
+++ b/test/sync.bats
@@ -0,0 +1,373 @@
+#!/usr/bin/env bats
+# EGB-1230 / EGB-1231: store sync — loud failures on `pull`, and a `secrets
+# sync` verb that reconciles a diverged store instead of dead-ending.
+#
+# bash 3.2 gotcha (see CLAUDE.md): every standalone [[ ]] assertion MUST end
+# with `|| false`, or a failing assertion does not fail the test.
+
+load test_helper
+
+# ─── fixtures ──────────────────────────────────────────────────────────
+#
+# A "peer" is a second clone of the same bare remote. Committing + pushing
+# from the peer is how we put the store under test *behind* its remote
+# without touching the store itself.
+
+peer_commit_and_push() {
+  local name="${1:-peer-file}" content="${2:-peer}"
+  local peer="$TEST_TMPDIR/peer"
+  if [ ! -d "$peer" ]; then
+    git clone "$REMOTE_DIR" "$peer" >/dev/null 2>&1
+  fi
+  ( cd "$peer" && git pull >/dev/null 2>&1 || true )
+  echo "$content" > "$peer/$name"
+  ( cd "$peer" && git add -A && git commit -m "peer: $name" >/dev/null && git push >/dev/null 2>&1 )
+}
+
+# Give the store a local-only commit (store becomes "ahead").
+store_local_commit() {
+  local name="${1:-local-file}"
+  echo "local" > "$SECRETS_DIR/$name"
+  git -C "$SECRETS_DIR" add -A
+  git -C "$SECRETS_DIR" commit -m "local: $name" >/dev/null
+}
+
+# Leave an uncommitted modification in the store working tree ("dirty").
+store_dirty() {
+  echo "scratch" > "$SECRETS_DIR/${1:-dirty-file}"
+  git -C "$SECRETS_DIR" add -A >/dev/null 2>&1 || true
+}
+
+store_head() { git -C "$SECRETS_DIR" rev-parse HEAD; }
+
+# init_with_remote (shared helper) commits --allow-empty, which leaves the
+# files `secrets init` wrote — .gitignore, .secrets-format, recipients.txt —
+# untracked. That is a genuinely dirty store, so tests that assert on the
+# "nothing to reconcile" path must land them first.
+init_clean_store() {
+  init_with_remote
+  git -C "$SECRETS_DIR" add -A
+  git -C "$SECRETS_DIR" commit -m "store: initial files" >/dev/null 2>&1 || true
+  git -C "$SECRETS_DIR" push >/dev/null 2>&1
+}
+
+# ─── EGB-1230: pull must never fail silently ───────────────────────────
+
+@test "EGB-1230: pull surfaces git's diagnosis when the store can't fast-forward" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt   # now diverged: ahead 1, behind 1
+
+  create_project_dir divproj
+  run "$SECRETS_BIN" pull
+
+  [ "$status" -ne 0 ]
+  # The failure is named, not silent — this is the whole bug.
+  [[ "$output" == *"Store sync failed"* ]] || false
+  [[ "$output" == *"$SECRETS_DIR"* ]] || false
+}
+
+@test "EGB-1230: pull's sync failure points at secrets sync" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+
+  create_project_dir divproj
+  run "$SECRETS_BIN" pull
+
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"secrets sync"* ]] || false
+}
+
+@test "EGB-1230: pull writes the diagnosis to stderr, not just stdout" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+
+  create_project_dir divproj
+  run bash -c "'$SECRETS_BIN' pull 2>&1 1>/dev/null"
+
+  [[ "$output" == *"Store sync failed"* ]] || false
+}
+
+@test "EGB-1230: a clean store still pulls normally" {
+  init_with_remote
+  create_project_dir cleanproj
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+
+  rm -f .env .env.staging
+  run "$SECRETS_BIN" pull
+  [ "$status" -eq 0 ]
+  [ -f .env ]
+}
+
+@test "EGB-1230: pull's sync is fast-forward only (no silent merge commit)" {
+  init_with_remote
+  create_project_dir ffproj
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+
+  local before; before=$(store_head)
+  run "$SECRETS_BIN" pull
+  [ "$status" -ne 0 ]
+  # A merge commit would have moved HEAD. Nothing was integrated.
+  [ "$(store_head)" = "$before" ]
+}
+
+# ─── EGB-1231: which reports store state ───────────────────────────────
+
+@test "EGB-1231: which reports ahead/behind/dirty for a diverged store" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+  git -C "$SECRETS_DIR" fetch origin >/dev/null 2>&1
+
+  create_project_dir whichproj
+  run "$SECRETS_BIN" which
+
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"remote:"* ]] || false
+  [[ "$output" == *"ahead 1"* ]] || false
+  [[ "$output" == *"behind 1"* ]] || false
+}
+
+@test "EGB-1231: which reports an in-sync store as up to date" {
+  init_clean_store
+  create_project_dir syncedproj
+  run "$SECRETS_BIN" which
+
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"remote:"* ]] || false
+  [[ "$output" == *"up to date"* ]] || false
+}
+
+@test "EGB-1231: which stays quiet about the remote when none is configured" {
+  run "$SECRETS_BIN" init
+  create_project_dir noremote
+  run "$SECRETS_BIN" which
+
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"remote:"* ]] || false
+}
+
+@test "EGB-1231: which reports a dirty store working tree" {
+  init_with_remote
+  store_dirty scratch.age
+  create_project_dir dirtyproj
+  run "$SECRETS_BIN" which
+
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"modified"* ]] || false
+}
+
+# ─── EGB-1231: secrets sync reconciles ─────────────────────────────────
+
+@test "EGB-1231: sync rebases a diverged store onto the remote" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+
+  run "$SECRETS_BIN" sync --yes
+  [ "$status" -eq 0 ]
+
+  # Both sides' work survives the reconcile.
+  [ -f "$SECRETS_DIR/remote-only.txt" ]
+  [ -f "$SECRETS_DIR/local-only.txt" ]
+}
+
+@test "EGB-1231: sync leaves the store able to pull again" {
+  init_with_remote
+  create_project_dir recovered
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+
+  run "$SECRETS_BIN" sync --yes
+  [ "$status" -eq 0 ]
+
+  rm -f .env .env.staging
+  run "$SECRETS_BIN" pull
+  [ "$status" -eq 0 ]
+  [ -f .env ]
+}
+
+@test "EGB-1231: sync fast-forwards a store that is only behind" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+
+  run "$SECRETS_BIN" sync --yes
+  [ "$status" -eq 0 ]
+  [ -f "$SECRETS_DIR/remote-only.txt" ]
+}
+
+@test "EGB-1231: sync stashes and restores a dirty working tree" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  echo "uncommitted work" > "$SECRETS_DIR/scratch.age"
+
+  run "$SECRETS_BIN" sync --yes
+  [ "$status" -eq 0 ]
+  [ -f "$SECRETS_DIR/remote-only.txt" ]
+  # The local uncommitted blob edit is NOT lost.
+  [ -f "$SECRETS_DIR/scratch.age" ]
+  [ "$(cat "$SECRETS_DIR/scratch.age")" = "uncommitted work" ]
+}
+
+@test "EGB-1231: sync on an already-clean store reports no work and changes nothing" {
+  init_clean_store
+  local before; before=$(store_head)
+
+  run "$SECRETS_BIN" sync --yes
+  [ "$status" -eq 0 ]
+  [ "$(store_head)" = "$before" ]
+  [[ "$output" == *"up to date"* ]] || false
+}
+
+@test "EGB-1231: sync dies directed when the store has no remote" {
+  run "$SECRETS_BIN" init
+  run "$SECRETS_BIN" sync --yes
+
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"no remote"* ]] || false
+}
+
+# ─── EGB-1231: --dry-run changes nothing ───────────────────────────────
+
+@test "EGB-1231: sync --dry-run reports state without mutating the store" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+
+  local before; before=$(store_head)
+  run "$SECRETS_BIN" sync --dry-run
+
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"ahead 1"* ]] || false
+  [[ "$output" == *"behind 1"* ]] || false
+  [ "$(store_head)" = "$before" ]
+  [ ! -f "$SECRETS_DIR/remote-only.txt" ]
+}
+
+@test "EGB-1231: sync --dry-run does not push local commits" {
+  init_with_remote
+  store_local_commit local-only.txt
+
+  run "$SECRETS_BIN" sync --dry-run
+  [ "$status" -eq 0 ]
+
+  # The remote never received the local commit.
+  run git -C "$REMOTE_DIR" log --oneline
+  [[ "$output" != *"local: local-only.txt"* ]] || false
+}
+
+# ─── EGB-1231: the push gate ───────────────────────────────────────────
+
+@test "EGB-1231: sync --yes pushes reconciled local commits to the remote" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+
+  run "$SECRETS_BIN" sync --yes
+  [ "$status" -eq 0 ]
+
+  run git -C "$REMOTE_DIR" log --oneline
+  [[ "$output" == *"local: local-only.txt"* ]] || false
+}
+
+@test "EGB-1231: sync without confirmation reconciles locally but does not push" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+
+  # No tty and no --yes: the push gate must not open on its own.
+  run bash -c "'$SECRETS_BIN' sync < /dev/null"
+  [ "$status" -eq 0 ]
+
+  # Local reconcile happened...
+  [ -f "$SECRETS_DIR/remote-only.txt" ]
+  # ...but nothing was published to the shared store.
+  run git -C "$REMOTE_DIR" log --oneline
+  [[ "$output" != *"local: local-only.txt"* ]] || false
+}
+
+@test "EGB-1231: sync says how to publish when the push gate stays closed" {
+  init_with_remote
+  store_local_commit local-only.txt
+
+  run bash -c "'$SECRETS_BIN' sync < /dev/null"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"--yes"* ]] || false
+}
+
+# ─── EGB-1231: conflicts restore the store as found ────────────────────
+
+@test "EGB-1231: a rebase conflict leaves the store exactly as it was" {
+  init_with_remote
+  # Both sides edit the same path — a guaranteed rebase conflict.
+  peer_commit_and_push contested.txt "from-remote"
+  git -C "$SECRETS_DIR" fetch origin >/dev/null 2>&1
+  echo "from-local" > "$SECRETS_DIR/contested.txt"
+  git -C "$SECRETS_DIR" add -A
+  git -C "$SECRETS_DIR" commit -m "local: contested" >/dev/null
+
+  local before; before=$(store_head)
+  run "$SECRETS_BIN" sync --yes
+
+  [ "$status" -ne 0 ]
+  [ "$(store_head)" = "$before" ]
+  # No half-finished rebase left behind for the user to trip over.
+  [ ! -d "$SECRETS_DIR/.git/rebase-merge" ]
+  [ ! -d "$SECRETS_DIR/.git/rebase-apply" ]
+  [ "$(cat "$SECRETS_DIR/contested.txt")" = "from-local" ]
+}
+
+@test "EGB-1231: a rebase conflict names the conflicting files" {
+  init_with_remote
+  peer_commit_and_push contested.txt "from-remote"
+  git -C "$SECRETS_DIR" fetch origin >/dev/null 2>&1
+  echo "from-local" > "$SECRETS_DIR/contested.txt"
+  git -C "$SECRETS_DIR" add -A
+  git -C "$SECRETS_DIR" commit -m "local: contested" >/dev/null
+
+  run "$SECRETS_BIN" sync --yes
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"contested.txt"* ]] || false
+}
+
+@test "EGB-1231: sync never force-pushes or hard-resets" {
+  # Guard rail on the implementation itself: this store holds the only
+  # copy of encrypted secrets, so the destructive git verbs must not
+  # appear anywhere in the sync path.
+  run bash -c "sed -n '/^cmd_sync()/,/^}/p' '$SECRETS_BIN'"
+  [[ "$output" != *"--force"* ]] || false
+  [[ "$output" != *"reset --hard"* ]] || false
+  [[ "$output" != *"stash drop"* ]] || false
+}
+
+# ─── EGB-1231: the push path's advice is no longer a dead end ──────────
+
+@test "EGB-1231: push's fast-forward failure points at secrets sync" {
+  init_with_remote
+  peer_commit_and_push remote-only.txt
+  store_local_commit local-only.txt
+
+  create_project_dir pushproj
+  run "$SECRETS_BIN" push
+
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"secrets sync"* ]] || false
+}
+
+# ─── help ──────────────────────────────────────────────────────────────
+
+@test "EGB-1231: sync is documented in help" {
+  run "$SECRETS_BIN" help
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"secrets sync"* ]] || false
+}

From f1cf9d9e7efbff45ce4fde808bf931530e43644c Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Tue, 8 Sep 2026 14:31:16 -0700
Subject: [PATCH 18/20] docs: correct Codeberg tea invocation in CLAUDE.md

`tea` autodetection fails in this repo, and the machine carries a second
login (`egbt`) pointing at a different forge that tea silently falls back
to in non-interactive mode. Document the explicit
`--login codeberg --repo egbt/secrets` form for every verb.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrUoYuUMoTj91rzV4vxGPB
---
 CLAUDE.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8bfe715..ff8405f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -150,10 +150,17 @@ The remote is Codeberg (Forgejo) — `gh`/`glab` do NOT work here. Use `tea`
 (login name: `codeberg`, user `egbt`) for forge operations when a skill's
 platform detection comes up "unknown":
 
-- PRs: `tea pr create --base main --title ... --description ...` / `tea pr merge <index>`
-- Releases: `tea releases create --tag v<X.Y.Z.W> --title "v<X.Y.Z.W> — <YYYY-MM-DD>" --note ...`
+**Always pass `--login codeberg --repo egbt/secrets` explicitly.** `tea`'s
+repo autodetection fails here ("remote repository required"), and this machine
+also has an `egbt` login pointing at a *different* forge
+(`https://git.dev.egbt.com`) that `tea` will silently fall back to in
+non-interactive mode — which would target the wrong server. Confirm with
+`tea logins list` if a command errors.
+
+- PRs: `tea pr create --login codeberg --repo egbt/secrets --base main --head <branch> --title ... --description ...` / `tea pr merge <index> --login codeberg --repo egbt/secrets`
+- Releases: `tea releases create --login codeberg --repo egbt/secrets --tag v<X.Y.Z.W> --title "v<X.Y.Z.W> — <YYYY-MM-DD>" --note ...`
   (convention: one release per tag, title `v<X.Y.Z.W> — <date>`)
-- Issues/status: `tea issues`, `tea pr list`
+- Issues/status: `tea issues --login codeberg --repo egbt/secrets`, `tea pr list --login codeberg --repo egbt/secrets`
 - No CI on this repo: the bats suite run locally is the merge gate.
 
 ## Environment variable

From c09ac38b16fab356b55a8d6d6c1c811cad20b91e Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Tue, 8 Sep 2026 15:22:04 -0700
Subject: [PATCH 19/20] fix: discover workspaces in pnpm and yarn monorepos
 (EGB-1232)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Workspace patterns came from package.json's `workspaces` key only, at both
call sites. pnpm declares them in pnpm-workspace.yaml instead, so no pnpm
monorepo ever resolved a workspace: `push -w` refused outright, and plain
`push` failed silently — _maybe_workspace_env_files returned 0 the moment
the key was absent, leaving the auto-discovery that covers push's root-only
scan inert and printing "Nothing new to add", indistinguishable from a repo
with genuinely nothing new. That silence cost two sessions on the same repo.

Both call sites now resolve through one shared source, _workspace_patterns:
package.json when it declares any, else pnpm-workspace.yaml's `packages:`
block. The YAML read is deliberately not a parser — block sequence only,
stopping at the next top-level key so pnpm 10's onlyBuiltDependencies:/
catalog: cannot leak in as globs, with quote/comment handling and a symlink
refusal.

Also fixes yarn's object form. `.workspaces // .workspaces.packages | .[]`
short-circuits on the truthy object, iterating its values and yielding the
pattern array as one token; only npm's array form ever worked. Note the
obvious reorder is NOT the fix — `.workspaces.packages` errors on an array —
so the filter is type-aware.

Patterns are validated before reaching the unquoted glob expansion (no
absolute paths, `..`, metacharacters, or whitespace; pnpm `!` negations
skipped), matching the .secrets-store/.secrets-files posture. jq is now
required only when package.json is the source. A monorepo-shaped root that
resolves nothing warns and points at `secrets add` instead of returning in
silence, and `-w`'s error names pnpm-workspace.yaml when that is the file
present.

Scope note: the workspace re-scan still runs only for projects that already
have a .secrets.json — push's root-scan-only first push is by design
(EGB-677 E13), and this bug is the fallback covering it never engaging.

test/workspaces.bats: 18 new tests. Full suite 371/371 green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrUoYuUMoTj91rzV4vxGPB
---
 CHANGELOG.md         |  41 ++++++
 CLAUDE.md            |   3 +-
 README.md            |  21 ++-
 VERSION              |   2 +-
 secrets              | 164 +++++++++++++++++++++--
 test/workspaces.bats | 300 +++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 517 insertions(+), 14 deletions(-)
 create mode 100644 test/workspaces.bats

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e7cde1..9152d7e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to a four-digit MAJOR.MINOR.PATCH.MICRO version scheme.
 
+## [0.7.7.0] - 2026-09-08
+
+### Fixed
+
+- **pnpm monorepos discovered no workspace secrets (EGB-1232)** — both
+  workspace call sites resolved patterns from `package.json`'s `workspaces`
+  key only, which pnpm does not use (it declares `packages:` in
+  `pnpm-workspace.yaml`). `secrets push -w` refused outright; plain `secrets
+  push` failed *silently* — `_maybe_workspace_env_files` returned 0 the moment
+  the key was absent, so the auto-discovery that exists to cover push's
+  root-only scan was inert on every pnpm repo and printed "Nothing new to
+  add", indistinguishable from a repo that genuinely had nothing. Workspace
+  patterns now resolve through one shared source that falls back to
+  `pnpm-workspace.yaml`.
+- **yarn's object `workspaces` form was never expanded (EGB-1232)** — the
+  filter `.workspaces // .workspaces.packages | .[]` short-circuits on yarn's
+  truthy object, so `.workspaces.packages` was never evaluated and `.[]`
+  iterated the object's values, yielding the pattern array itself as a single
+  token. Only npm's array form worked. Now type-aware, handling npm's array,
+  yarn's object, and absent/null alike.
+
+### Added
+
+- **`pnpm-workspace.yaml` support** — the `packages:` block sequence is read
+  without a YAML dependency: block form only, stopping at the next top-level
+  key so pnpm 10's `onlyBuiltDependencies:`/`catalog:` cannot leak in as glob
+  patterns, with quote and inline-comment handling and a symlink refusal.
+  `package.json` wins when it declares workspaces; `pnpm-workspace.yaml` is the
+  fallback. jq is now required only when `package.json` is the source, so a
+  pnpm-only repo resolves workspaces jq-free.
+- **Workspace patterns are validated before glob expansion** — no absolute
+  paths, `..` traversal, shell metacharacters, or whitespace reach the
+  unquoted expansion; pnpm `!` negations are skipped. Same conservative rail
+  as `.secrets-store` / `.secrets-files`.
+- **A monorepo-shaped root that resolves no workspaces now says so** — if a
+  `pnpm-workspace.yaml` or `packages/` directory is present but no workspace
+  packages can be read, `push` warns on stderr and points at `secrets add`,
+  instead of returning in silence. `secrets push -w`'s error now names
+  `pnpm-workspace.yaml` when that is the file present, rather than blaming a
+  `package.json` the repo may not use for workspaces.
+
 ## [0.7.6.0] - 2026-09-08
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index ff8405f..2729c0e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -66,7 +66,7 @@ Single bash script (`secrets`) with subcommands: init, push, pull, list, rm, rek
 - Store sync + divergence (EGB-1230/EGB-1231): the store is a git repo, so a clone can end up ahead of and behind its remote at once. **EGB-1230:** `cmd_pull`'s sync used to be `git pull >/dev/null 2>&1` under `set -euo pipefail` — a store that couldn't fast-forward killed the script there with git's exit 128 and nothing on either stream (a banner, no files, no reason; invisible in a pipeline). It now routes through `_store_sync_pull`, which guards the pull, captures git's output as the diagnosis, and dies naming the store path and `secrets sync`. That sync is **`--ff-only`**, matching the push path — a plain `git pull` could quietly manufacture a merge commit in the store, and divergence is now resolved in exactly one place. **EGB-1231:** `_store_git_state` emits `ahead\tbehind\tdirty` (from `rev-list --left-right --count @{u}...HEAD` plus `status --porcelain`) and `_format_store_state` renders it; `cmd_which` prints a `remote:` line from them — offline-safe (reports against the last fetch), silent with no remote/upstream. `cmd_sync` is the reconcile verb the CLI was missing: fetch → report state → stash (`push -u`) → `rebase @{u}` → restore stash → `ensure_store_protections` (rebased-in history may lack `.gitignore`, and a store missing the `key.txt` line would stage the private key — same reasoning as push) → **confirmation-gated** `git push` of local commits. The gate (`_sync_confirm_push`) reads `/dev/tty` and requires a tty, so it stays CLOSED in scripts/CI rather than publishing to a shared store by default; `--yes` opens it, `--dry-run` reports and returns before any mutation. Non-destructive by construction: no merge, no `--force`, no `reset --hard`, no `stash drop`. A rebase conflict collects the conflicting paths BEFORE `rebase --abort` (the abort clears them), restores the stash, and dies — store byte-identical to how it was found. `_sync_restore_stash` never drops the stash on a failed pop; it tells the operator where their only copy lives. `cmd_sync` does not `_stamp_writer_version`: it replays existing commits rather than authoring content, and the stamp is specified to ride a store-committing `git add -A`. Test suite: `test/sync.bats` (25 tests), including a grep over the `cmd_sync` body asserting the destructive git verbs never appear in it.
 - Verify (EGB-698): `secrets verify` is a read-only integrity check. Default mode (current project) cross-checks `$PWD/.secrets.json` against `$SECRETS_DIR/<project>/` both ways (declared-but-missing blobs + orphaned blobs) and decrypt-tests every blob (dotenv + external) by streaming plaintext to `/dev/null` (never written to disk). `secrets verify --all` decrypt-tests every blob in every project (integrity only — the store carries no manifests, so consistency can't be checked store-wide). Both recurse the whole project tree (`find -type f`, same as rekey/list). Exits non-zero on any finding so it can gate the stage-2 `migrate --finalize` and CI. The store deliberately holds no manifest — `.secrets.json` is committed in each project's own repo and read from `$PWD`.
 - External files: `.secrets-files` manifest tracks designated keys from files outside the project (e.g. `~/.gradle/gradle.properties`, merged not overwritten — EGB-531) and whole binary files (type `file`, e.g. an Android upload keystore — EGB-652); see below
-- Workspaces: `--workspaces` flag reads `package.json` workspaces, requires `jq`
+- Workspaces (EGB-1232): `--workspaces` and the plain-push workspace re-scan both resolve patterns through ONE source — `_workspace_patterns()`. It reads `package.json` `.workspaces` via `$WORKSPACES_JQ` (type-aware: handles npm's array AND yarn's object `{packages:[...]}` form) and falls back to `pnpm-workspace.yaml`'s `packages:` block when package.json declares none. **Two defects fixed:** (1) both call sites were package.json-only, so no pnpm monorepo ever resolved a workspace — and `_maybe_workspace_env_files` failed *silently* (`jq -e '.workspaces' ... || return 0`), making auto-discovery inert and `push` print "Nothing new to add", indistinguishable from a repo with nothing new; it bit the same repo twice. (2) the old filter `.workspaces // .workspaces.packages | .[]` short-circuits on yarn's truthy object, iterating the object's values and yielding the pattern ARRAY as a single token. Note a naive reorder does NOT fix it — `.workspaces.packages` errors on an array; hence the `if type == "object"` form. `_pnpm_workspace_packages()` is a deliberate non-parser (block sequence only, stops at the next top-level key so pnpm 10's `onlyBuiltDependencies:`/`catalog:` can't leak in as globs, strips quotes/inline comments, refuses a symlinked file). Patterns are validated by `_valid_workspace_pattern` before they reach the unquoted `for pattern in $patterns` glob expansion (no absolute/`..`/metacharacters/whitespace; pnpm `!` negations skipped) — same posture as `.secrets-store`/`.secrets-files`. `_looks_like_monorepo` + `_workspace_source` turn the old silent return into a warning that names the real file, and `get_workspaces`'s error names `pnpm-workspace.yaml` when that's what's present instead of blaming package.json. jq is required only when package.json is the source. **Scope note:** the workspace re-scan still runs only for projects that already have a `.secrets.json` — push's root-scan-only behavior on a first push is by design (EGB-677 E13), and EGB-1232 is about the fallback that covers it never engaging. Tests: `test/workspaces.bats` (18).
 - Safety: Pre-commit hook rejects plaintext secret files (`.env`, `.dev.vars`, `gradle.properties`)
 - Multi-recipient (EGB-283): a store-scoped, committed `recipients.txt` (age `-R`
   format, `# name` comments) lets one store encrypt every blob to N age keys —
@@ -99,6 +99,7 @@ test/
   migrate.bats       # EGB-703 store-format-v2 migration tests (35 tests)
   upgrade.bats       # EGB-716 `secrets upgrade` self-update tests (8 tests)
   sync.bats          # EGB-1230/1231 store sync + divergence reconcile tests (25 tests)
+  workspaces.bats    # EGB-1232 npm/yarn/pnpm workspace discovery tests (18 tests)
   recipients.bats    # EGB-283 multi-recipient age encryption tests (34 tests)
   test_helper.bash   # Shared setup/teardown
 README.md            # User-facing documentation
diff --git a/README.md b/README.md
index f838ad5..697101b 100644
--- a/README.md
+++ b/README.md
@@ -425,10 +425,10 @@ git commit -am "switch to personal secrets"
 
 ### Monorepo support
 
-For projects with multiple packages (monorepos using `package.json` workspaces), add the `-w` flag to operate on all workspaces at once:
+For projects with multiple packages, add the `-w` flag to operate on all workspaces at once:
 
 ```bash
-cd ~/myapp                  # has package.json with "workspaces": ["apps/*", "packages/*"]
+cd ~/myapp                  # npm/yarn workspaces, or a pnpm-workspace.yaml
 secrets push -w             # encrypts secrets from root + each workspace
 secrets pull -w             # decrypts into root + each workspace directory
 secrets clear -w            # clears secrets from root + each workspace
@@ -445,7 +445,22 @@ Inside `~/.secrets/`, workspace secrets are organized by path:
     apps/api/.env.age               # api workspace
 ```
 
-Requires `jq` (`brew install jq`).
+**Where workspaces are declared.** All three package managers are supported:
+
+| Manager | Declaration |
+|---|---|
+| npm | `package.json` → `"workspaces": ["apps/*"]` |
+| yarn | `package.json` → `"workspaces": {"packages": ["apps/*"]}` |
+| pnpm | `pnpm-workspace.yaml` → `packages:` block |
+
+`package.json` wins when it declares any workspaces; `pnpm-workspace.yaml` is
+the fallback. Reading `package.json` requires `jq` (`brew install jq`); a
+pnpm-only repo needs no jq for workspace discovery.
+
+If a root *looks* like a monorepo (a `pnpm-workspace.yaml` or a `packages/`
+directory) but no workspace packages can be read from it, `secrets push` says
+so on stderr rather than silently discovering nothing — that silence
+previously made a pnpm repo indistinguishable from one with nothing to sync.
 
 ### External files (Gradle properties)
 
diff --git a/VERSION b/VERSION
index 29e2792..d5ba5b5 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.7.6.0
+0.7.7.0
diff --git a/secrets b/secrets
index 8d947dc..00ce9b3 100755
--- a/secrets
+++ b/secrets
@@ -986,6 +986,14 @@ pull_external_files() {
 SECRETS_JSON_NAME=".secrets.json"
 MANIFEST_VERSION=2
 
+# EGB-1232: package.json workspaces, type-aware. The old filter was
+# `.workspaces // .workspaces.packages` — `//` short-circuits on yarn's
+# truthy OBJECT form, so `.workspaces.packages` was never evaluated and
+# `.[]` iterated the object's values, yielding the pattern array itself
+# rather than the patterns. Only npm's array form ever worked. Reordering
+# alone is not the fix either: `.workspaces.packages` errors on an array.
+WORKSPACES_JQ='(.workspaces | if type == "object" then .packages else . end) // empty | .[]?'
+
 # Validate a project-relative dotenv path from the manifest (or `secrets
 # add`). The path is attacker-influenced in team repos (committed file),
 # so this is a security rail, not just hygiene. Prints an error and
@@ -1233,9 +1241,22 @@ _legacy_absorb_json() {
 # after the one-time --workspaces generator run (EGB-677 E13).
 _maybe_workspace_env_files() {
   local root="$1"
-  [ -f "$root/package.json" ] || return 0
-  command -v jq >/dev/null 2>&1 || return 0
-  jq -e '.workspaces' "$root/package.json" >/dev/null 2>&1 || return 0
+  # EGB-1232: this used to require package.json + a `.workspaces` key and
+  # `return 0` otherwise — so on every pnpm repo the guard fired immediately,
+  # auto-discovery was inert, and `push` printed "Nothing new to add",
+  # indistinguishable from a repo that genuinely had nothing. The silence was
+  # the damaging half of the bug: it cost two sessions on the same repo.
+  local patterns
+  patterns=$(_workspace_patterns "$root")
+  if [ -z "$patterns" ]; then
+    if _looks_like_monorepo "$root"; then
+      local src; src=$(_workspace_source "$root") || src="$root"
+      echo "WARNING: $(basename "$src") is present but declares no readable workspace packages —" >&2
+      echo "  workspace env files were NOT discovered. Declare them explicitly with:" >&2
+      echo "    secrets add <path/to/.env>" >&2
+    fi
+    return 0
+  fi
   local ws f
   while IFS= read -r ws; do
     [ -n "$ws" ] || continue
@@ -1249,17 +1270,142 @@ _maybe_workspace_env_files() {
 
 # ─── End manifest ──────────────────────────────────────────────────────
 
-# Read package.json workspaces and expand globs to actual directories.
+# ─── Workspace pattern sources (EGB-1232) ──────────────────────────────
+#
+# One source of pattern truth for every caller. Both call sites used to read
+# package.json's `workspaces` key ONLY, so no pnpm monorepo ever resolved a
+# workspace — pnpm declares them in pnpm-workspace.yaml instead.
+
+# A committed project file whose contents get word-split and glob-expanded
+# below, so it gets the same conservative rail as .secrets-store/.secrets-files:
+# no absolute paths, no traversal, no shell metacharacters, no whitespace.
+# pnpm's `!`-prefixed negations are not directory patterns and are skipped.
+_valid_workspace_pattern() {
+  case "$1" in
+    "")   return 1 ;;
+    /*)   return 1 ;;
+    *..*) return 1 ;;
+    '!'*) return 1 ;;
+    *[!A-Za-z0-9/._*@-]*) return 1 ;;
+  esac
+  return 0
+}
+
+# Read the `packages:` block sequence out of a pnpm-workspace.yaml.
+# Deliberately not a YAML parser — one top-level key, block sequence form,
+# which is what pnpm writes. Stops at the next top-level key so pnpm 10's
+# sibling keys (onlyBuiltDependencies:, catalog:, …) can never leak in as
+# glob patterns. Symlinked file refused, matching the other manifest readers.
+_pnpm_workspace_packages() {
+  local f="$1"
+  [ -f "$f" ] || return 0
+  if [ -L "$f" ]; then
+    echo "WARNING: $f is a symlink — skipping it." >&2
+    return 0
+  fi
+  local line lead trimmed item in_block=0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line%$'\r'}"
+    lead="${line%%[![:space:]]*}"
+    trimmed="${line#"$lead"}"
+    [ -n "$trimmed" ] || continue
+    case "$trimmed" in '#'*) continue ;; esac
+
+    if [ "$in_block" -eq 0 ]; then
+      # Only a top-level `packages:` opens the block.
+      if [ -z "$lead" ]; then
+        case "$trimmed" in packages:*) in_block=1 ;; esac
+      fi
+      continue
+    fi
+
+    # Inside the block: a line at column 0 that is not a list item is the
+    # next top-level key, which ends it.
+    if [ -z "$lead" ]; then
+      case "$trimmed" in -*) ;; *) break ;; esac
+    fi
+    case "$trimmed" in -*) ;; *) continue ;; esac
+
+    item="${trimmed#-}"
+    lead="${item%%[![:space:]]*}"
+    item="${item#"$lead"}"
+    # Quoted forms take everything up to the closing quote (so a trailing
+    # `# comment` never lands in the pattern); bare forms stop at a comment.
+    case "$item" in
+      \"*) item="${item#\"}"; item="${item%%\"*}" ;;
+      \'*) item="${item#\'}"; item="${item%%\'*}" ;;
+      *)   item="${item%%#*}"; item="${item%"${item##*[![:space:]]}"}" ;;
+    esac
+    [ -n "$item" ] && printf '%s\n' "$item"
+  done < "$f"
+}
+
+# The file that supplies (or should have supplied) this root's workspace
+# patterns — so errors name the file that actually exists rather than
+# blaming package.json on a repo that doesn't use it.
+_workspace_source() {
+  local root="$1"
+  if [ -f "$root/package.json" ] && command -v jq >/dev/null 2>&1 \
+     && [ -n "$(jq -r "$WORKSPACES_JQ" "$root/package.json" 2>/dev/null)" ]; then
+    printf '%s' "$root/package.json"; return 0
+  fi
+  [ -f "$root/pnpm-workspace.yaml" ] && { printf '%s' "$root/pnpm-workspace.yaml"; return 0; }
+  [ -f "$root/package.json" ] && { printf '%s' "$root/package.json"; return 0; }
+  return 1
+}
+
+# Does this root look like a monorepo even though no patterns resolved?
+# Used to turn the old silent `return 0` into something a user can act on.
+_looks_like_monorepo() {
+  local root="$1"
+  [ -f "$root/pnpm-workspace.yaml" ] && return 0
+  [ -d "$root/packages" ] && return 0
+  if [ -f "$root/package.json" ] && command -v jq >/dev/null 2>&1; then
+    jq -e '.workspaces' "$root/package.json" >/dev/null 2>&1 && return 0
+  fi
+  return 1
+}
+
+# Validated workspace glob patterns for a root, one per line.
+# package.json wins when it declares any; pnpm-workspace.yaml is the fallback.
+_workspace_patterns() {
+  local root="$1" patterns="" p out=""
+  if [ -f "$root/package.json" ] && command -v jq >/dev/null 2>&1; then
+    patterns=$(jq -r "$WORKSPACES_JQ" "$root/package.json" 2>/dev/null || true)
+  fi
+  if [ -z "$patterns" ]; then
+    patterns=$(_pnpm_workspace_packages "$root/pnpm-workspace.yaml")
+  fi
+  while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    if _valid_workspace_pattern "$p"; then
+      out="$out$p"$'\n'
+    else
+      echo "WARNING: ignoring unsafe workspace pattern: $p" >&2
+    fi
+  done <<< "$patterns"
+  printf '%s' "$out"
+}
+
+# Expand a root's workspace patterns to actual directories.
 # Prints one workspace path per line (relative to the monorepo root).
 get_workspaces() {
   local root="$1"
-  local pkg="$root/package.json"
-  [ -f "$pkg" ] || die "No package.json found in $root"
-  check_cmd jq
 
   local patterns
-  patterns=$(jq -r '.workspaces // .workspaces.packages // empty | .[]' "$pkg" 2>/dev/null)
-  [ -n "$patterns" ] || die "No workspaces field in $pkg"
+  patterns=$(_workspace_patterns "$root")
+  if [ -z "$patterns" ]; then
+    # A package.json we can't read for want of jq is a tooling problem, not a
+    # missing declaration — say which it is.
+    if [ -f "$root/package.json" ] && [ ! -f "$root/pnpm-workspace.yaml" ] \
+       && ! command -v jq >/dev/null 2>&1; then
+      check_cmd jq
+    fi
+    local src
+    src=$(_workspace_source "$root") \
+      || die "No package.json or pnpm-workspace.yaml found in $root"
+    die "No workspaces declared in $src"
+  fi
 
   # Expand each glob pattern relative to root
   local old_dir="$PWD"
diff --git a/test/workspaces.bats b/test/workspaces.bats
new file mode 100644
index 0000000..280196f
--- /dev/null
+++ b/test/workspaces.bats
@@ -0,0 +1,300 @@
+#!/usr/bin/env bats
+# EGB-1232: workspace discovery must not be npm-only.
+#
+# Two defects, both in the pattern-source layer:
+#   1. pnpm declares workspaces in pnpm-workspace.yaml, not package.json's
+#      `workspaces` key — so both call sites came up empty on every pnpm
+#      monorepo (silently, in the plain-push path).
+#   2. the jq filter `.workspaces // .workspaces.packages` short-circuits on
+#      yarn's truthy object form, iterating the object's values and yielding
+#      the pattern array itself instead of the patterns.
+#
+# bash 3.2 gotcha (see CLAUDE.md): every standalone [[ ]] assertion MUST end
+# with `|| false`, or a failing assertion does not fail the test.
+
+load test_helper
+
+# ─── fixtures ──────────────────────────────────────────────────────────
+
+# A monorepo root with two workspace packages, each holding a .env.
+# The workspace *declaration* is left to the caller — that is what varies.
+# NB: the workspace re-scan (_maybe_workspace_env_files) runs only for
+# projects that already have a .secrets.json — push's root-scan-only
+# behaviour on a first push is by design (EGB-677 E13), and EGB-1232 is
+# about the fallback that covers it never engaging. So every fixture
+# carries a manifest, matching the reported repro.
+make_monorepo() {
+  local dir="$WORK_DIR/${1:-mono}"
+  mkdir -p "$dir/apps/web" "$dir/apps/admin"
+  echo "VITE_CLERK_PUBLISHABLE_KEY=pk_test_web" > "$dir/apps/web/.env"
+  echo "VITE_CLERK_PUBLISHABLE_KEY=pk_test_admin" > "$dir/apps/admin/.env"
+  printf '{\n  "version": 2,\n  "dotenv": [],\n  "external": []\n}\n' > "$dir/.secrets.json"
+  cd "$dir"
+}
+
+declare_pnpm() {
+  cat > pnpm-workspace.yaml <<'YAML'
+packages:
+  - "apps/*"
+  - "packages/*"
+YAML
+  echo '{"name":"mono","private":true}' > package.json
+}
+
+declare_npm() {
+  echo '{"name":"mono","private":true,"workspaces":["apps/*"]}' > package.json
+}
+
+declare_yarn_object() {
+  echo '{"name":"mono","private":true,"workspaces":{"packages":["apps/*"]}}' > package.json
+}
+
+# ─── the pnpm gap (the reported bug) ───────────────────────────────────
+
+@test "EGB-1232: push discovers workspace env files in a pnpm monorepo" {
+  init_with_remote
+  make_monorepo pnpmrepo
+  declare_pnpm
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"apps/web/.env"* ]] || false
+  [[ "$output" == *"apps/admin/.env"* ]] || false
+}
+
+@test "EGB-1232: push actually vaults pnpm workspace env files" {
+  init_with_remote
+  make_monorepo pnpmreal
+  declare_pnpm
+
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+
+  rm -f apps/web/.env apps/admin/.env
+  run "$SECRETS_BIN" pull
+  [ "$status" -eq 0 ]
+  [ -f apps/web/.env ]
+  [ -f apps/admin/.env ]
+  # The value that was empty in the .env.example — the actual impact.
+  [[ "$(cat apps/web/.env)" == *"pk_test_web"* ]] || false
+}
+
+@test "EGB-1232: push -w works on a pnpm monorepo" {
+  init_with_remote
+  make_monorepo pnpmw
+  declare_pnpm
+
+  run "$SECRETS_BIN" push -w
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"No workspaces field"* ]] || false
+}
+
+@test "EGB-1232: pnpm-workspace.yaml is read without requiring a package.json" {
+  init_with_remote
+  make_monorepo pnpmnopkg
+  cat > pnpm-workspace.yaml <<'YAML'
+packages:
+  - "apps/*"
+YAML
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"apps/web/.env"* ]] || false
+}
+
+# ─── pnpm YAML parsing edge cases ──────────────────────────────────────
+
+@test "EGB-1232: pnpm parsing stops at the next top-level key" {
+  init_with_remote
+  make_monorepo pnpmkeys
+  # pnpm 10+ carries sibling top-level keys. They must not leak in as globs.
+  cat > pnpm-workspace.yaml <<'YAML'
+packages:
+  - "apps/*"
+
+onlyBuiltDependencies:
+  - esbuild
+  - sharp
+
+catalog:
+  react: ^18.0.0
+YAML
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"apps/web/.env"* ]] || false
+  [[ "$output" != *"esbuild"* ]] || false
+  [[ "$output" != *"sharp"* ]] || false
+}
+
+@test "EGB-1232: pnpm parsing handles quotes, bare entries, and comments" {
+  init_with_remote
+  make_monorepo pnpmquotes
+  mkdir -p docs && echo "DOCS=1" > docs/.env
+  cat > pnpm-workspace.yaml <<'YAML'
+# which packages belong to this workspace
+packages:
+  - "apps/*"      # double quoted, with a trailing comment
+  - 'docs'        # single quoted, no glob
+YAML
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"apps/web/.env"* ]] || false
+  [[ "$output" == *"docs/.env"* ]] || false
+}
+
+@test "EGB-1232: a pnpm-workspace.yaml with no packages key discovers nothing and says so" {
+  init_with_remote
+  make_monorepo pnpmempty
+  cat > pnpm-workspace.yaml <<'YAML'
+onlyBuiltDependencies:
+  - esbuild
+YAML
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"pnpm-workspace.yaml"* ]] || false
+}
+
+# ─── the yarn object-form defect ───────────────────────────────────────
+
+@test "EGB-1232: yarn's object workspaces form is expanded, not iterated" {
+  init_with_remote
+  make_monorepo yarnobj
+  declare_yarn_object
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"apps/web/.env"* ]] || false
+  [[ "$output" == *"apps/admin/.env"* ]] || false
+}
+
+@test "EGB-1232: yarn object form works under -w" {
+  init_with_remote
+  make_monorepo yarnobjw
+  declare_yarn_object
+
+  run "$SECRETS_BIN" push -w
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"No workspaces field"* ]] || false
+}
+
+# ─── npm regression guard ──────────────────────────────────────────────
+
+@test "EGB-1232: npm's array workspaces form still works" {
+  init_with_remote
+  make_monorepo npmarr
+  declare_npm
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"apps/web/.env"* ]] || false
+  [[ "$output" == *"apps/admin/.env"* ]] || false
+}
+
+@test "EGB-1232: package.json workspaces wins when both sources are present" {
+  init_with_remote
+  make_monorepo bothsrc
+  mkdir -p only-pnpm && echo "P=1" > only-pnpm/.env
+  echo '{"name":"mono","workspaces":["apps/*"]}' > package.json
+  cat > pnpm-workspace.yaml <<'YAML'
+packages:
+  - "only-pnpm"
+YAML
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"apps/web/.env"* ]] || false
+  [[ "$output" != *"only-pnpm/.env"* ]] || false
+}
+
+# ─── diagnostics: the silence is the bug ───────────────────────────────
+
+@test "EGB-1232: a monorepo-shaped root with no readable workspace source warns" {
+  init_with_remote
+  make_monorepo shaped
+  # Looks like a monorepo (pnpm-workspace.yaml present) but declares nothing.
+  echo "# nothing useful here" > pnpm-workspace.yaml
+  # A root .env so the push SUCCEEDS — the dangerous case is a green push
+  # that silently skipped every workspace, which is what bit thatsbait.
+  echo "ROOT=1" > .env
+
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"WARNING"* ]] || false
+  [[ "$output" == *"workspace"* ]] || false
+}
+
+@test "EGB-1232: the warning tells you how to recover" {
+  init_with_remote
+  make_monorepo shapedfix
+  echo "# nothing useful here" > pnpm-workspace.yaml
+  echo "ROOT=1" > .env
+
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"secrets add"* ]] || false
+}
+
+@test "EGB-1232: a plain single-package project never warns about workspaces" {
+  init_with_remote
+  create_project_dir plainproj
+  printf '{\n  "version": 2,\n  "dotenv": [],\n  "external": []\n}\n' > .secrets.json
+
+  run "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"workspace"* ]] || false
+}
+
+@test "EGB-1232: push -w names pnpm-workspace.yaml when that is the file present" {
+  init_with_remote
+  make_monorepo wnames
+  echo '{"name":"mono"}' > package.json
+  echo "# no packages key" > pnpm-workspace.yaml
+
+  run "$SECRETS_BIN" push -w
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"pnpm-workspace.yaml"* ]] || false
+}
+
+@test "EGB-1232: push -w still names package.json when no pnpm file exists" {
+  init_with_remote
+  make_monorepo wnamespkg
+  echo '{"name":"mono"}' > package.json
+
+  run "$SECRETS_BIN" push -w
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"package.json"* ]] || false
+}
+
+# ─── path safety ───────────────────────────────────────────────────────
+
+@test "EGB-1232: a pnpm packages entry cannot escape the project root" {
+  init_with_remote
+  make_monorepo escapee
+  echo "OUTSIDE=1" > "$WORK_DIR/outside.env"
+  cat > pnpm-workspace.yaml <<'YAML'
+packages:
+  - "../"
+  - "/etc"
+YAML
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"outside.env"* ]] || false
+  [[ "$output" != *"/etc/"* ]] || false
+}
+
+@test "EGB-1232: a pnpm packages entry with shell metacharacters is refused" {
+  init_with_remote
+  make_monorepo metachars
+  cat > pnpm-workspace.yaml <<'YAML'
+packages:
+  - "apps/*; touch /tmp/egb1232-pwned"
+YAML
+
+  run "$SECRETS_BIN" push --dry-run
+  [ "$status" -eq 0 ]
+  [ ! -f /tmp/egb1232-pwned ]
+}

From d984e2abc7e98be248b9bb2a1953b61c414337bf Mon Sep 17 00:00:00 2001
From: Brian Majewski <brian.majewski@gmail.com>
Date: Tue, 8 Sep 2026 16:00:54 -0700
Subject: [PATCH 20/20] docs: repoint forge references from Codeberg to
 git.dev.egbt.com
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The origin moved to the private Forgejo instance at git.dev.egbt.com
(egbt/secrets). Git history, all 16 branches, 13 tags, and all 13 releases
were migrated with identical SHAs and release bodies.

- CLAUDE.md: replace the "Codeberg operations" section with "Forge
  operations", switching tea invocations to `--login egbt --repo
  egbt/secrets`. Records three things that are easy to get wrong:
  Forgejo's SSH listens on port 2222 (port 22 is the host's own sshd, so
  a bare git@host:path fails with "Permission denied (publickey)"); the
  host is Tailscale-only, so off-VPN failures are connectivity, not
  credentials; and the stale `codeberg` tea login is still configured and
  can be silently fallen back to in non-interactive mode.
- CLAUDE.md: note the instance has an Actions runner available, though no
  workflow is configured yet — local bats remains the merge gate.
- README.md: clone URLs now point at the new host.
- CHANGELOG.md: release links now point at the new host.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrUoYuUMoTj91rzV4vxGPB
---
 CHANGELOG.md |  6 +++---
 CLAUDE.md    | 36 ++++++++++++++++++++++++------------
 README.md    |  6 +++---
 3 files changed, 30 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9152d7e..4bee6fb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -475,6 +475,6 @@ and this project adheres to a four-digit MAJOR.MINOR.PATCH.MICRO version scheme.
 
 - 37 → 66 tests. New coverage: store resolution rules and precedence, walk-up boundaries, command-injection prevention, key-file re-derivation across stores, teammate-onboarding error path, monorepo workspace binding, F1–F5 adversarial regressions.
 
-[0.1.1.0]: https://codeberg.org/egbt/secrets/releases/tag/v0.1.1.0
-[0.1.0.1]: https://codeberg.org/egbt/secrets/releases/tag/v0.1.0.1
-[0.1.0.0]: https://codeberg.org/egbt/secrets/releases/tag/v0.1.0.0
+[0.1.1.0]: https://git.dev.egbt.com/egbt/secrets/releases/tag/v0.1.1.0
+[0.1.0.1]: https://git.dev.egbt.com/egbt/secrets/releases/tag/v0.1.0.1
+[0.1.0.0]: https://git.dev.egbt.com/egbt/secrets/releases/tag/v0.1.0.0
diff --git a/CLAUDE.md b/CLAUDE.md
index 2729c0e..a0261b8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -138,31 +138,43 @@ Key design decisions (all driven by /autoplan review):
 
 ## Deploy Configuration
 
-- Platform: NONE (distributed via `git clone` from Codeberg)
+- Platform: NONE (distributed via `git clone` from the private Forgejo at `git.dev.egbt.com`)
 - Production URL: N/A (no live service)
 - Release model: merge to `main` is the release. Optionally tagged with `v<X.Y.Z.W>`.
 - Verification after merge: a fresh `git clone` should produce a working `secrets which` against an isolated `$HOME`. No canary URL.
 - Staging: none.
 - Rollback: revert the merge commit on `main` (and delete the tag) to roll back.
 
-## Codeberg operations
+## Forge operations (self-hosted Forgejo)
 
-The remote is Codeberg (Forgejo) — `gh`/`glab` do NOT work here. Use `tea`
-(login name: `codeberg`, user `egbt`) for forge operations when a skill's
+The remote is a private Forgejo instance at `https://git.dev.egbt.com`
+(migrated off Codeberg 2026-09-08). `gh`/`glab` do NOT work here. Use `tea`
+(login name: `egbt`, user `brian`) for forge operations when a skill's
 platform detection comes up "unknown":
 
-**Always pass `--login codeberg --repo egbt/secrets` explicitly.** `tea`'s
-repo autodetection fails here ("remote repository required"), and this machine
-also has an `egbt` login pointing at a *different* forge
-(`https://git.dev.egbt.com`) that `tea` will silently fall back to in
+**Always pass `--login egbt --repo egbt/secrets` explicitly.** `tea`'s repo
+autodetection fails here ("remote repository required"), and this machine also
+has a leftover `codeberg` login pointing at the *old* forge
+(`https://codeberg.org`) that `tea` will silently fall back to in
 non-interactive mode — which would target the wrong server. Confirm with
 `tea logins list` if a command errors.
 
-- PRs: `tea pr create --login codeberg --repo egbt/secrets --base main --head <branch> --title ... --description ...` / `tea pr merge <index> --login codeberg --repo egbt/secrets`
-- Releases: `tea releases create --login codeberg --repo egbt/secrets --tag v<X.Y.Z.W> --title "v<X.Y.Z.W> — <YYYY-MM-DD>" --note ...`
+- PRs: `tea pr create --login egbt --repo egbt/secrets --base main --head <branch> --title ... --description ...` / `tea pr merge <index> --login egbt --repo egbt/secrets`
+- Releases: `tea releases create --login egbt --repo egbt/secrets --tag v<X.Y.Z.W> --title "v<X.Y.Z.W> — <YYYY-MM-DD>" --note ...`
   (convention: one release per tag, title `v<X.Y.Z.W> — <date>`)
-- Issues/status: `tea issues --login codeberg --repo egbt/secrets`, `tea pr list --login codeberg --repo egbt/secrets`
-- No CI on this repo: the bats suite run locally is the merge gate.
+- Issues/status: `tea issues --login egbt --repo egbt/secrets`, `tea pr list --login egbt --repo egbt/secrets`
+- **SSH is on port 2222**, not 22 (port 22 is the host's own sshd). Clone/remote
+  URLs must be `ssh://git@git.dev.egbt.com:2222/egbt/secrets.git`. A bare
+  `git@git.dev.egbt.com:egbt/secrets.git` will fail with "Permission denied
+  (publickey)" because it hits the wrong daemon.
+- The host resolves to a Tailscale address — the forge is reachable only on the
+  VPN. Off-net, push/pull/`tea` all fail to connect; that is expected, not a
+  credentials problem.
+- `FORGEJO_URL` and `FORGEJO_TOKEN` (API token for user `brian`) live in
+  `~/.zshenv` for direct API calls.
+- CI: the instance has an Actions runner available, but no workflow is
+  configured for this repo yet. The bats suite run locally is still the merge
+  gate.
 
 ## Environment variable
 
diff --git a/README.md b/README.md
index 697101b..acfd2b4 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,7 @@ two commands to finish setup. It never edits your shell config and never runs
 sudo — it prints the commands so you stay in control.
 
 ```bash
-git clone https://codeberg.org/egbt/secrets.git ~/dev/secrets
+git clone https://git.dev.egbt.com/egbt/secrets.git ~/dev/secrets
 cd ~/dev/secrets
 ./install.sh
 ```
@@ -82,7 +82,7 @@ this machine with one of the two flows below.
 
 ```bash
 # 1. Create a PRIVATE repo for your encrypted secrets (github.com/new or a
-#    Codeberg/GitLab private repo). It holds only ciphertext — never your key.
+#    GitLab/Forgejo private repo). It holds only ciphertext — never your key.
 #    Then wire it up and push the store in one command:
 secrets init --remote git@github.com:<you>/my-secrets.git
 
@@ -108,7 +108,7 @@ On a second machine, a desktop, or a teammate's laptop:
 
 ```bash
 # 1. Clone the tool and run the bootstrap (as in Setup above)
-git clone https://codeberg.org/egbt/secrets.git ~/dev/secrets
+git clone https://git.dev.egbt.com/egbt/secrets.git ~/dev/secrets
 cd ~/dev/secrets && ./install.sh   # add the printed PATH line to your shell config
 
 # 2. Get key.txt onto this machine (the one manual, out-of-band step):