I'll start by exploring the repository structure and searching for key symbols in parallel.

<analysis>
**Literal Request**: Trace the `activate_customer` normal path, every production caller, RoomBootstrapStore state transition APIs, transaction/rollback boundaries, and cleanup expectations in `/home/cube/projects/richard/hermes-agent`.

**Actual Need**: Find the single safest insertion point to transition a customer-bound bootstrap session from AWAITING_ACTIVATION->ACTIVE without direct ledger edits, duplicate activation, partial commit, or wrong-session ambiguity. Identify existing tests and the exact new regression seam.

**Success Looks Like**: A clear map of the activation flow, state machine, transaction boundaries, all callers, and a precise recommendation for where (and how) to insert the state transition.
</analysis>


I have the map. Note the `build/lib` directory appears to be a stale copy — I'll focus on `gateway/` (live source). Let me read the core files.


Now let me read the key caller files — the `activate_customer` implementation, the `_recover_room_bootstrap_waiting_states` function, and the onboarding runtime files that check `AWAITING_ACTIVATION`:


The `activate_customer` lives in the profile-local `checkin_cli.customer_admin`. Let me find it:


Now let me look at `start_after_consent` caller in telegram.py and the `activate-cutover` command referenced in the runbook, plus the `NutritionOnboardingReconciler` and the `telegram.py` code around line 5929 where `start_after_consent` is called:


Let me find the `activate-cutover` script and read the runbook, plus examine the test files and the checkin_cli path


Let me look at the `activate-cutover` script and the test files more closely:


The runbook references `scripts/nutrition-room-bootstrap` but my `find` didn't locate it. Let me search more precisely:


The `nutrition-room-bootstrap` CLI and `checkin_cli.customer_admin` are external (profile-local), not in this repo. Let me verify who calls `store.transition(...)` with target ACTIVE, and read the publication mixin and the key tests:


Excellent. Now let me read the `recover_waiting_session` test and the `test_telegram_customer_bootstrap.py` for AWAITING_ACTIVATION -> ACTIVE tests:


I found a critical anomaly: the test `test_customer_activation_commits_only_the_exact_bound_session` calls `store.activate_bound_customer(...)`, but the store I read has no such method. Let me verify:


There it is -- `activate_bound_customer` exists at line 428. My earlier read of the file somehow didn't include it (it was at 428 but I read 233-428 and the file is ~1126 lines, so it should have appeared unless the file was truncated or the method is defined lower). Let me re-read the area around line 428:


Now the picture is clear. My first read was truncated by size; `activate_bound_customer` exists at line 428. Let me verify it's a live-source addition (absent from the stale `build/lib`) and find any in-repo production callers or wrapper scripts


Let me read the full test for `activate_bound_customer` (the retry/idempotency case at lines 100-160) — this defines the exact regression seam:


I have the full picture. Let me do a final check for any in-repo production entry point that invokes the activation (CLI, bot command, or script), to definitively answer "every production caller":


I now have complete evidence. No further searching needed.

<results>
<files>
- /home/cube/projects/richard/hermes-agent/gateway/platforms/telegram_customer_bootstrap.py - Single source of truth for `RoomBootstrapStore`, `BootstrapState`, the CAS/generation state machine, and the `activate_bound_customer` activation API.
- /home/cube/projects/richard/hermes-agent/gateway/platforms/telegram_customer_bootstrap_registration.py - Registration side: drives REGISTERING→AWAITING_CONSENT (via `store.transition` + `bind_private_owner`) and loads profile-local `checkin_cli.customer_admin`.
- /home/cube/projects/richard/hermes-agent/gateway/platforms/telegram.py - Adapter orchestration; `_recover_room_bootstrap_waiting_states()` (line 4945) and `start_after_consent()` caller (line 5929) are the gateway's only AWAITING_ACTIVATION-handling call sites.
- /home/cube/projects/richard/hermes-agent/gateway/platforms/telegram_nutrition_onboarding_runtime.py - `recover_waiting_session()` (line 177) and `start_after_consent()` (line 97): the AWAITING_ACTIVATION recovery/resume logic. Does NOT advance bootstrap state to ACTIVE.
- /home/cube/projects/richard/hermes-agent/gateway/platforms/telegram_nutrition_onboarding_runtime_authority.py - `_session_for_customer_message()` only returns sessions whose `state is AWAITING_ACTIVATION`; the customer isolation gate.
- /home/cube/projects/richard/hermes-agent/gateway/platforms/telegram_nutrition_onboarding_runtime_collection.py & `..._callback.py` - Ingress/callback gates that require `AWAITING_ACTIVATION`; reject any other bootstrap state.
- /home/cube/projects/richard/hermes-agent/tests/gateway/test_telegram_customer_bootstrap.py - Contains the exact regression seam: `test_customer_activation_commits_only_the_exact_bound_session` (line 90) and the idempotency/reject-wrong-identity test (line 100).
- /home/cube/projects/richard/hermes-agent/tests/gateway/test_telegram_room_bootstrap_adversarial.py - Restart/recovery test asserting AWAITING_ACTIVATION survives restart and `recover_waiting_session` is invoked but state is untouched.
- /home/cube/projects/richard/hermes-agent/tests/gateway/test_telegram_nutrition_onboarding.py (line 1200) - `recover_waiting_session` just republishes the durable card under AWAITING_ACTIVATION.
- /home/cube/projects/richard/hermes-agent/docs/nutrition-coaching/trainer-runbook-ko.md - Specifies the explicit operator cutover (`scripts/nutrition-room-bootstrap activate-cutover`, `--execute`) that is the intended production caller; the CLI itself is NOT in this repo (it lives in the profile's `workspace/checkin_cli`).
</files>

<answer>
**The single safest insertion point already exists: `RoomBootstrapStore.activate_bound_customer` at `gateway/platforms/telegram_customer_bootstrap.py:428`.** It is purpose-built for exactly the AWAITING_ACTIVATION→ACTIVE transition with all four required guarantees, and it is the only boundary that satisfies them jointly.

**How it satisfies each constraint:**
- *No direct ledger edits* — it is the sole authorized store API; `_write_unlocked` (line ~440) is private, atomic (tempfile + fsync + `os.replace` + dir fsync), and digest-checked on read. Callers cannot hand-write `ledger.json`.
- *No duplicate activation* — idempotent replay: if the session is already `ACTIVE`, it accepts `expected_generation in {generation-1, generation}` and returns the existing object (no generation bump); plus the `active_matches` guard rejects creating a second ACTIVE session for the same `customer_key`.
- *No partial commit* — single `fcntl.flock(LOCK_EX)` across read+write; generation CAS (raises `GenerationConflict` on stale generation); `_find` requires exactly one matching `session_id` (raises `BootstrapError` on ambiguity). Either the whole update persists or nothing does.
- *No wrong-session ambiguity* — exact identity match on `customer_key`, `customer_draft.customer_user_id`, `owner_id`, plus a single customer `RoleClaim` with `topic_id=="0"`; mismatch raises `BootstrapConflict("...activation identity is unavailable")`. There is no shared-room authority in this design (session `chat_id` is `None`), so the only unambiguous handle is `session_id` + customer claim.

**Why not `transition()` (line 401):** `transition()` *does* allow `AWAITING_ACTIVATION→ACTIVE`, but it is a generic state command with no identity/customer/single-active binding — it would permit activating the wrong session or a second ACTIVE for the same customer. `activate_bound_customer` is the typed, identity-bound completion called for by the runbook rule that the ACTIVE transition "cannot be done by a generic state-change command."

**Every production caller of the explicit path:**
- `activate_customer`/`disable_customer` live in the profile-local `checkin_cli.customer_admin`, loaded by `TelegramCustomerBootstrapRegistration._profile_modules` from `$PROFILE_ROOT/workspace/checkin_cli` — not in this repo.
- The operator CLI `scripts/nutrition-room-bootstrap activate-cutover --execute` (documented in the runbook, invoked from the host, not present in `/home/cube/projects/richard/hermes-agent`) is the intended caller that retires the current customer via `disable_customer`, activates the target via `activate_customer`, then commits the bootstrap `ACTIVE` transition.
- Inside this repo there is **zero runtime caller** of `activate_bound_customer` (verified: the only references are the definition and the tests). The gateway's AWAITING_ACTIVATION handlers (`_recover_room_bootstrap_waiting_states` → `recover_waiting_session`; `start_after_consent`) only re-publish cards / resume the service and **never advance the bootstrap state to ACTIVE**.

**Transaction/rollback boundaries:** entire store is file-locked and CAS-generational; every transition writes once atomically and throws (GenerationConflict / BootstrapError / BootstrapConflict) before any write on validation failure, so a failed call leaves the ledger byte-identical (the tests assert this). The `activate_bound_customer` method re-implements this locking inline rather than via `_mutate`, but with the same semantics.

**Failure semantics:** stale generation → `GenerationConflict`; identity mismatch → `BootstrapConflict`; session missing/ambiguous → `BootstrapError`; recovery (`recover_waiting_session`) swallows OSError/TypeError/ValueError and leaves state untouched, returning `False`/logging.

**Cleanup expectations after ACTIVE:** per runbook §대량: exactly one active customer, customers/trainer routes and current consent exact, a committed activation journal/audit receipt, and adaptive `activation`/`delivery` + profile `delivery_enabled` all `false`. `recover_waiting_session` handles the resumable cleanup (republication + owner callback receipt reconciliation).

**Existing tests / new regression seam:**
- `tests/gateway/test_telegram_customer_bootstrap.py::test_customer_activation_commits_only_the_exact_bound_session` (line ~90) — full walk to AWAITING_ACTIVATION then `activate_bound_customer` → ACTIVE, asserting exact bound session.
- `...::test_customer_activation_rejects_wrong_identity_and_is_idempotent` (line ~100) — asserts `BootstrapError("identity")` on wrong `customer_user_id`, that ledger is unchanged, and that a replayed call with the pre-commit generation returns the identical committed session.
- New regression assertions should go in these two tests: (1) exactly one ACTIVE row per `customer_key` after a second candidate tries to activate; (2) a replay passing `generation-1` returns the same object without a further generation increment.

**Would the change require a larger redesign?** Two very different intents:
- If the goal is "route the transition through `activate_bound_customer` / confirm the correct seam" — **no redesign**: the method, state machine, atomicity, and tests already exist.
- If the goal is to have the **gateway auto-transition** to ACTIVE (e.g., inside `recover_waiting_session` or after `start_after_consent`) — **yes, that is a deliberate architectural barrier**: activation is an explicit operator cutover gated by the g1-g5 checklist, current-customer retirement, and a canonical journal/audit receipt. Auto-advancing from the gateway would bypass that gate and could violate the single-active + activation/delivery-disabled invariants the ledger is designed to protect. The intended seam keeps the gateway at AWAITING_ACTIVATION and lets the typed external CLI complete activation.
</answer>

<next_steps>
If you intend to add gateway-side activation, the correct move is to call the pre-existing `RoomBootstrapStore.activate_bound_customer()` at the point where you have proven identity + generation (i.e., after `reconcile_committed_consent` returns AWAITING_ACTIVATION in `telegram.py`), and extend `test_telegram_customer_bootstrap.py` with the single-active and idempotent-replay assertions. If the intended change is auto-activation inside `recover_waiting_session`/`start_after_consent`, stop and treat it as a redesign that must preserve the operator cutover gate and single-active invariant. The most reliable path is to keep activation owned by the external `nutrition-room-bootstrap activate-cutover` CLI, which your repo can only reach by adding the missing production caller for `activate_bound_customer` — that insertion, not a new activation implementation, is where the work belongs.
</next_steps>
</results>