## What
Extend `scripts/buzz-adopt-prod-agents.sh` to copy
`agents/global-agent-config.json` from the prod app-data store to dev as
part of the existing atomic bundle commit, and document what the script
cannot copy (baked build-time defaults).
## Why
`global-agent-config.json` holds the owner's global agent defaults
(`env_vars`, `provider`, `model`, `preferred_runtime`). Previously the
script carried the dev copy across verbatim — it was absent from the
bundle drop list and not in `RECORD_FILES`. After a `just reset`, the
dev build inherited stale global defaults (or none at all) instead of
mirroring prod, inconsistent with how all other bundle files are
handled.
The "WHAT THIS DOES NOT DO" header lacked any mention of baked
build-time defaults, which are a separate (and common) source of
prod/dev parity confusion.
## Changes
- **`RECORD_FILES`** — add `global-agent-config.json`. The file has no
volatile fields (`GlobalAgentConfig` struct =
`env_vars`/`provider`/`model`/`preferred_runtime`), so it joins the
verbatim-copy path already used by `teams.json` — no new transform.
- **Stage-seed block** — add `global-agent-config.json` to the `rm -rf`
drop list so the prod overlay replaces it cleanly; remove its stale
mention in the "carried verbatim" comment.
- **Docs/comments** — update "4-file bundle" → "5-file bundle" in the
DMG concurrent-run warning and the step 2 comment; list the file
explicitly in the step 2 header comment.
- **"WHAT THIS DOES NOT DO" header** — add a bullet explaining that
baked build-time agent defaults (`BUZZ_BUILD_BUZZ_AGENT_PROVIDER` /
`BUZZ_BUILD_AGENT_ENV` via `option_env!` in `build.rs`) are compiled
into the binary, not stored in app-data. Includes the correct `just
production` invocation pattern and a `.env` warning.
- **Preflight symlink checks and dry-run output** iterate `RECORD_FILES`
and pick up the new entry automatically — no other changes needed.
Verified: `bash -n` clean, `shellcheck` clean, `--dry-run --force` shows
`[dry-run] stage global-agent-config.json (0600)` in the expected
position.
---------
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
Adds `scripts/buzz-adopt-prod-agents.sh`, which copies the installed-DMG
(production) agent records and owner identity into the dev app-data
store so a dev build boots as the **same agents and same owner npub** as
the installed app — surviving `just reset`.
## What it restores
`just reset` wipes the two things Buzz cannot re-derive:
- The agent **records** — `managed-agents.json`, `personas.json`,
`teams.json`, and `agents/teams/`.
- The **owner identity** nsec, written as `identity.key` (0600, atomic).
Agent private keys and identity-key adoption then happen automatically
on the next dev boot via the shipped in-app migrations.
## When to run it
1. Quit any running **dev** build. A running installed DMG is fine — the
script treats it as a read-only source and only warns against
creating/archiving agents or editing teams while it runs. It never kills
processes.
2. Run `just reset`.
3. Before the first dev boot, run `bash
scripts/buzz-adopt-prod-agents.sh`.
- `--dry-run` prints every action with zero writes.
- `--force` overwrites an already-populated dev store.
- One keychain prompt is expected (reading the prod owner identity).
4. Start the dev build. First boot copies the agent keys prod→dev and
adopts `identity.key`, then deletes it. For worktree launches, export
`BUZZ_SHARE_IDENTITY=1` (and `BUZZ_PRIVATE_KEY`) or the worktree mints
its own duplicate agents.
## Running-process check
Only a running **dev** build blocks the run: the script atomically swaps
the entire dev `agents/` directory and stages `identity.key` for the
next dev boot to consume, so doing that under a live dev process is the
corruption the check must prevent. A running installed DMG is allowed —
the app writes `managed-agents.json` via tmp+atomic-rename, so it can
never hand the script a torn file. Each matching `buzz-desktop` PID is
classified by its true post-exec executable path (via `lsof -d txt`,
which reports the running vnode with symlinks already resolved); the
installed `/Applications/Buzz.app/Contents/MacOS/buzz-desktop` path is
the only allow. Anything else still alive blocks fail-closed; a PID that
exits before its path can be resolved is ignored.
## Requirements
Requires `python3` when a dev `agents/` already exists — it drives the
`renamex_np(RENAME_SWAP)` syscall bash cannot call. The script fails in
preflight with a clear message if `python3` is absent, never mid-commit.
## Safety
Prod is strictly read-only; symlinked or aliased prod/dev roots are
refused before any write. The records/identity restore commits in one
atomic operation (`renamex_np(RENAME_SWAP)` when a dev store exists, a
single `mv` when absent) that fails closed — a crash or I/O error leaves
`agents/` either fully old or fully new, and unrelated live dev state
(`logs/`, `agent-pids/`, `global-agent-config.json`, retention stores)
is preserved verbatim across the swap.
This is a temporary measure while we trial it and decide whether to port
the logic into the dev-build startup path.
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
