booking-agent-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: booking-agent-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: The Booking Agent CLI: a stateful USP booking flow with hard gates, plus its USP protocol library.
 Project-URL: Homepage, https://github.com/wix/booking-agent
 Project-URL: Documentation, https://github.com/wix/booking-agent/blob/master/booking-agent/README.md
@@ -78,7 +78,7 @@ Each release also publishes that skill at an immutable `skill-v<version>` tag an
 the release workflow, so a harness can pin and verify the exact text it follows:
 
 ```bash
-curl -fsSLO https://raw.githubusercontent.com/wix/booking-agent/skill-v0.53.0/booking-agent/skills/booking-agent/SKILL.md
+curl -fsSLO https://raw.githubusercontent.com/wix/booking-agent/skill-v0.54.0/booking-agent/skills/booking-agent/SKILL.md
 gh attestation verify SKILL.md --repo wix/booking-agent \
   --signer-workflow wix/booking-agent/.github/workflows/release.yml
 ```

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/README.md

@@ -36,7 +36,7 @@ Each release also publishes that skill at an immutable `skill-v<version>` tag an
 the release workflow, so a harness can pin and verify the exact text it follows:
 
 ```bash
-curl -fsSLO https://raw.githubusercontent.com/wix/booking-agent/skill-v0.53.0/booking-agent/skills/booking-agent/SKILL.md
+curl -fsSLO https://raw.githubusercontent.com/wix/booking-agent/skill-v0.54.0/booking-agent/skills/booking-agent/SKILL.md
 gh attestation verify SKILL.md --repo wix/booking-agent \
   --signer-workflow wix/booking-agent/.github/workflows/release.yml
 ```

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "booking-agent-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "The Booking Agent CLI: a stateful USP booking flow with hard gates, plus its USP protocol library."
 readme = "README.md"
 license = "Apache-2.0"

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/src/booking_agent/__init__.py

@@ -3,4 +3,4 @@
 Ships in the booking-agent-cli wheel and never imports ``booking_agent_cli``.
 """
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/src/booking_agent/defaults.env

@@ -14,6 +14,9 @@ USP_PLATFORM_CONTACT=support@booking-agent.dev
 # Sessions, tokens, and traces. Holds the user .env, so override it only in the
 # process environment.
 BOOKING_AGENT_SESSION_DIR=~/.booking-agent
+# Absolute folder a host keeps between runs. When set, booking-agent links its state and the
+# Link sign-in into it by itself before every command.
+# BOOKING_AGENT_PERSISTENT_ROOT=
 BOOKING_AGENT_MAX_SESSIONS=30
 LINK_CLI_BIN=link-cli
 

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/src/booking_agent_cli/__init__.py

@@ -1,3 +1,3 @@
 """booking_agent_cli: typer-based stateful CLI for USP booking flows."""
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/src/booking_agent_cli/bundled_skill.md

@@ -1,5 +1,5 @@
 ---
-version: 0.53.0
+version: 0.54.0
 name: booking-agent
 description: |
   Books time-based services via USP from a Link wallet. Use when the user wants to book, schedule, reserve, or pay for a service from a business (haircut, lesson, repair, class, appointment, consult). The `booking-agent` CLI owns the booking state machine and refuses to proceed when human gates are skipped. Sign the user in to Link on your own, right after install and at the start of every booking (`booking-agent flow link-auth connect`, then start `booking-agent flow link-auth poll` in the background and post the sign-in URL in the same turn, exactly like `pay poll`); never wait for the user to ask to sign in or to say they approved. After `booking-agent flow business use`, follow `next_command` through `use-ucp-checkout-mode`; businesses without native checkout fail closed. Payment uses `booking-agent flow pay request` (default returns immediately with the approval URL), then start `booking-agent flow pay poll` in the background and post the approval URL to the user in the same turn; the poll finishes checkout once they approve. Confirm through `booking-agent flow book poll --wait`; never start an inbound webhook. Surface the approval URL exactly once. Personal identification (name, phone, email, address) must always come from the user's Link account via `link-cli`, never from chat or placeholders. Before any location-based search, the CLI proposes the Link shipping address and the user confirms it or gives another; online services skip this. Talk to the user in plain everyday language only; never expose CLI, UCP, auth, session, or other implementation details unless they explicitly ask.
@@ -19,7 +19,7 @@ metadata:
         - link-cli
     install:
       - kind: uv
-        package: "booking-agent-cli==0.5.0"
+        package: "booking-agent-cli==0.6.0"
         bins: [booking-agent]
 user-invocable: true
 ---
@@ -220,7 +220,7 @@ To take a fixed, published version instead of the latest, fetch it at the releas
 workflow signs it under, and check the signature before you follow it:
 
 ```bash
-curl -fsSLO https://raw.githubusercontent.com/wix/booking-agent/skill-v0.53.0/booking-agent/skills/booking-agent/SKILL.md
+curl -fsSLO https://raw.githubusercontent.com/wix/booking-agent/skill-v0.54.0/booking-agent/skills/booking-agent/SKILL.md
 gh attestation verify SKILL.md \
   --repo wix/booking-agent \
   --signer-workflow wix/booking-agent/.github/workflows/release.yml
@@ -245,17 +245,17 @@ before installing:
 
 ```bash
 dir="$HOME/.booking-agent/verified-wheels"
-uvx pip download "booking-agent-cli==0.5.0" --no-deps --only-binary :all: -d "$dir"
+uvx pip download "booking-agent-cli==0.6.0" --no-deps --only-binary :all: -d "$dir"
 uvx pypi-attestations==0.0.30 verify pypi --repository https://github.com/wix/booking-agent \
-  "$dir/booking_agent_cli-0.5.0-py3-none-any.whl"
-uv tool install --force "$dir/booking_agent_cli-0.5.0-py3-none-any.whl"
+  "$dir/booking_agent_cli-0.6.0-py3-none-any.whl"
+uv tool install --force "$dir/booking_agent_cli-0.6.0-py3-none-any.whl"
 
 booking-agent --help
 ```
 
 Install only the wheel whose verify step passed, never one that failed it. If `uvx` is not
-available, install the same pinned release with `uv tool install booking-agent-cli==0.5.0` or
-`pipx install booking-agent-cli==0.5.0`; the CLI checks its own files against the signed release
+available, install the same pinned release with `uv tool install booking-agent-cli==0.6.0` or
+`pipx install booking-agent-cli==0.6.0`; the CLI checks its own files against the signed release
 on the first `booking-agent flow init` and refuses to book or pay if they do not match.
 
 Harnesses that read the `install` block in this skill's metadata do this for you. Do not go on
@@ -275,22 +275,22 @@ npm install -g @stripe/link-cli
 
 ### After installing
 
-**Keep state between conversations (only when this runtime needs it).** When this runtime's
-filesystem starts fresh in each conversation and it gives you a folder that survives between
-conversations, run this once per conversation, before `booking-agent flow sessions list`:
+**Keep state between conversations.** When the host names a folder that survives between
+conversations in `BOOKING_AGENT_PERSISTENT_ROOT`, the CLI links its state and the Link sign-in into
+it by itself before every command: do nothing and never mention it. Only when the variable is unset
+and this runtime gives you such a folder, run this once per conversation, before `booking-agent flow
+sessions list`:
 
 ```bash
 booking-agent runtime prepare --persistent-root <absolute folder that survives>
 ```
 
-It links the booking state and the Link sign-in into that folder, so saved bookings, calendar
-preferences, and the sign-in carry over. Use the same folder every time; a different one, or one
-already named `booking-agent`, moves the existing state along instead of splitting it. Add `--link
-<runtime folder>=<persistent folder>` for each extra cache folder the runtime asks you to keep (a
-relative persistent folder is placed under the root). If the user is asked to sign in or reconnect
-right after a restart, run `booking-agent runtime doctor` and follow its `next_command`. When the
-runtime keeps its files anyway, or offers no surviving folder, skip the command. Do not tell the
-user about it. If it fails, continue the booking without it.
+Use the same folder every time; it merges what each folder holds (booking files by session, the
+newer copy of anything else) and deletes nothing. Add `--link <runtime folder>=<persistent folder>`
+for each extra cache folder the runtime asks you to keep. If the user is asked to sign in or
+reconnect right after a restart, run `booking-agent runtime doctor` and follow its `next_command`.
+When the runtime keeps its files anyway, skip all of this. Do not tell the user about it. If it
+fails, continue the booking without it.
 
 **Sign the user in to Link**, as described in [Link sign-in](#link-sign-in-automatic). It works
 with no booking in progress. Do not wait for the user to offer to sign in.
@@ -309,7 +309,7 @@ prints each effective setting and where it came from; `booking-agent config init
 
 The CLI decides whether a newer version is worth mentioning; you never decide from version
 numbers or release pages. Pass this skill's version on every `flow init` (`--skill-version
-0.53.0`, from the frontmatter above), so the CLI can tell when these instructions and the
+0.54.0`, from the frontmatter above), so the CLI can tell when these instructions and the
 installed CLI no longer match.
 
 - When a command returns `awaiting_user: update_consent`, ask the question in `prompt` in plain
@@ -471,7 +471,7 @@ confirmation email or on the business's page (`booking_url`). Do not invent a lo
 **Step 1b — Create a new session:**
 
 ```bash
-booking-agent flow init --user-request "<user's exact request>" --skill-version 0.53.0 \
+booking-agent flow init --user-request "<user's exact request>" --skill-version 0.54.0 \
   --skill-path "<absolute path of the SKILL.md you loaded>"
 ```
 

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/src/booking_agent_cli/main.py

@@ -29,6 +29,15 @@ app.add_typer(runtime_app, name="runtime")
 app.add_typer(skill_app, name="skill")
 app.add_typer(update_app, name="update")
 
+@app.callback()
+def _main(ctx: typer.Context) -> None:
+    """Keep state in the host's persistent folder (when it names one) before any command runs."""
+    if ctx.invoked_subcommand != "runtime":
+        from .runtime_prepare import auto_prepare
+
+        auto_prepare()
+
+
 INTERNAL_ERROR_MESSAGE = (
     "The booking assistant hit an unexpected internal error. Tell the user in plain "
     "words that something went wrong on our side, then follow next_command."

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/src/booking_agent_cli/runtime_prepare.py

@@ -10,6 +10,7 @@ deleted, so file modes on credentials and keys stay as they were.
 """
 from __future__ import annotations
 
+import json
 import os
 import shutil
 import sys
@@ -18,11 +19,19 @@ from pathlib import Path
 from typing import Dict, List, Optional, Tuple
 
 from booking_agent import settings
-from booking_agent.secure_file import ensure_private_dir
+from booking_agent.secure_file import ensure_private_dir, write_private_text
 
 STATE_SUBDIR = "booking-agent"
 LINK_SUBDIR = "link-cli"
 _LINK_CLI_APP = "link-cli-nodejs"
+ROOT_ENV = "BOOKING_AGENT_PERSISTENT_ROOT"
+_SESSION_FILE = ".usp-session.json"
+# Order a booking moves through, used to keep the further-along copy of the same session.
+_PHASE_ORDER = (
+    "INIT", "PREREQ_OK", "BUSINESS_SELECTED", "CALENDAR_GATE", "AVAILABILITY_QUERIED",
+    "SLOTS_PRESENTED", "SLOT_SELECTED", "BUYER_RESOLVED", "BOOKED", "PAYMENT_PENDING",
+    "CONFIRMED", "FAILED",
+)
 
 
 class PrepareError(ValueError):
@@ -75,6 +84,117 @@ def _is_empty_dir(path: Path) -> bool:
     return path.is_dir() and not any(path.iterdir())
 
 
+def _phase_rank(session: Dict[str, object]) -> int:
+    phase = session.get("flow_phase")
+    return _PHASE_ORDER.index(phase) if phase in _PHASE_ORDER else -1
+
+
+def merge_session_stores(newer: Dict[str, object], older: Dict[str, object]) -> Dict[str, object]:
+    """Union of two saved booking files, by session id, without dropping any booking.
+
+    A session present in both keeps the copy that got further (a stale ``INIT`` snapshot never
+    hides the finished booking). Everything else at the top level comes from ``newer`` and falls
+    back to ``older``. Works on the raw JSON so fields this version does not know survive.
+    """
+    merged: Dict[str, object] = {**older, **{k: v for k, v in newer.items() if v is not None}}
+    by_id: Dict[object, Dict[str, object]] = {}
+    order: List[object] = []
+    for source in (older, newer):
+        for session in source.get("sessions") or []:
+            if not isinstance(session, dict):
+                continue
+            sid = session.get("id")
+            if sid not in by_id:
+                by_id[sid] = session
+                order.append(sid)
+            elif _phase_rank(session) >= _phase_rank(by_id[sid]):
+                by_id[sid] = session
+    merged["sessions"] = [by_id[sid] for sid in order]
+    for key in ("sessions_created", "schema_version"):
+        values = [v for v in (newer.get(key), older.get(key)) if isinstance(v, int)]
+        if values:
+            merged[key] = max(values)
+    answered = []
+    for source in (older, newer):
+        for item in source.get("update_prompts_answered") or []:
+            if isinstance(item, str) and item not in answered:
+                answered.append(item)
+    if answered:
+        merged["update_prompts_answered"] = answered
+    active = newer.get("active_session_id") or older.get("active_session_id")
+    merged["active_session_id"] = active if active in by_id else (order[-1] if order else None)
+    return merged
+
+
+def _merge_session_files(src: Path, dst: Path) -> None:
+    def _load(path: Path) -> Dict[str, object]:
+        try:
+            raw = json.loads(path.read_text())
+            return raw if isinstance(raw, dict) else {}
+        except (OSError, ValueError):
+            return {}
+
+    src_newer = src.stat().st_mtime >= dst.stat().st_mtime
+    a, b = _load(src), _load(dst)
+    merged = merge_session_stores(a, b) if src_newer else merge_session_stores(b, a)
+    write_private_text(dst, json.dumps(merged, indent=2, sort_keys=False))
+    src.unlink()
+
+
+def _merge_tree(src: Path, dst: Path, aside: Path, kept: List[str], rel: str = "") -> None:
+    """Move everything from ``src`` into ``dst``; nothing is deleted.
+
+    A name only in ``src`` moves over. Two folders merge. Two booking files merge by session.
+    Any other pair keeps the newer file at ``dst`` and moves the older one under ``aside``.
+    """
+    for child in sorted(src.iterdir()):
+        target = dst / child.name
+        here = f"{rel}/{child.name}" if rel else child.name
+        if not (target.exists() or target.is_symlink()):
+            shutil.move(str(child), str(target))
+        elif child.is_dir() and target.is_dir():
+            _merge_tree(child, target, aside, kept, here)
+            if _is_empty_dir(child):
+                child.rmdir()
+        elif child.name == _SESSION_FILE and child.is_file() and target.is_file():
+            _merge_session_files(child, target)
+        elif (
+            child.is_file() and target.is_file()
+            and child.stat().st_mtime > target.stat().st_mtime
+        ):
+            # The incoming file is newer: the older one at the destination is kept aside.
+            shutil.move(str(target), str(_aside_path(aside, here, kept)))
+            shutil.move(str(child), str(target))
+        else:
+            shutil.move(str(child), str(_aside_path(aside, here, kept)))
+
+
+def _aside_path(aside: Path, rel: str, kept: List[str]) -> Path:
+    path = aside / rel
+    path.parent.mkdir(parents=True, exist_ok=True)
+    kept.append(rel)
+    return path
+
+
+def merge_dir_into(src: Path, dst: Path, *, aside_name: str) -> Dict[str, str]:
+    """Merge folder ``src`` into ``dst``, then remove the (now empty) ``src``."""
+    aside = src.with_name(aside_name)
+    aside.mkdir(parents=True, exist_ok=True)
+    kept: List[str] = []
+    _merge_tree(src, dst, aside, kept)
+    if _is_empty_dir(src):
+        src.rmdir()
+    out = {"merged_existing_contents": "true"}
+    if kept:
+        out["older_copies_kept_at"] = str(aside)
+    else:
+        try:
+            aside.rmdir()
+        except OSError:
+            pass
+    return out
+
+
 def _move_children(src: Path, dst: Path) -> None:
     dst.mkdir(parents=True, exist_ok=True)
     for child in src.iterdir():
@@ -97,12 +217,14 @@ def link_one(runtime: Path, persistent: Path, *, private: bool) -> Dict[str, str
         # Linked into another root (a different conversation chose a different folder).
         # Bring that root's saved state along when this one has none; otherwise leave it alone.
         previous = runtime.resolve()
-        if previous.is_dir() and not _is_empty_dir(previous):
+        if previous.is_dir() and not _is_empty_dir(previous) and previous != persistent.resolve():
             if _is_empty_dir(persistent):
                 _move_children(previous, persistent)
                 out["moved_existing_contents"] = "true"
             else:
-                out["previous_root_left_at"] = str(previous)
+                out.update(merge_dir_into(
+                    previous, persistent, aside_name=f"{previous.name}.before-prepare-{int(time.time())}",
+                ))
         runtime.unlink()
         relinked = True
     elif runtime.exists():
@@ -116,10 +238,11 @@ def link_one(runtime: Path, persistent: Path, *, private: bool) -> Dict[str, str
             runtime.rmdir()
             out["moved_existing_contents"] = "true"
         else:
-            # Both hold data: the persistent copy wins, the runtime copy is kept aside.
-            aside = runtime.with_name(f"{runtime.name}.before-prepare-{int(time.time())}")
-            os.replace(runtime, aside)
-            out["kept_runtime_copy_at"] = str(aside)
+            # Both hold data: merge them. Booking files merge by session id; for any other
+            # file the newer copy stays and the older one is kept aside, never deleted.
+            out.update(merge_dir_into(
+                runtime, persistent, aside_name=f"{runtime.name}.before-prepare-{int(time.time())}",
+            ))
 
     runtime.parent.mkdir(parents=True, exist_ok=True)
     os.symlink(persistent, runtime, target_is_directory=True)
@@ -142,25 +265,28 @@ def normalized_root(persistent_root: str) -> Path:
 
 
 def _lift_nested_layout(root: Path) -> Dict[str, str]:
-    """Undo the old nested layout (``<root>/booking-agent/{booking-agent,link-cli}``)."""
+    """Undo the old nested layout (``<root>/booking-agent/{booking-agent,link-cli}``).
+
+    Both folders are merged into their proper place, so a stale top-level booking file never
+    hides the real one from the nested folder.
+    """
     state = root / STATE_SUBDIR
     lifted: Dict[str, str] = {}
+    stamp = int(time.time())
     nested_state = state / STATE_SUBDIR
     if nested_state.is_dir():
-        for child in list(nested_state.iterdir()):
-            if not (state / child.name).exists():
-                os.replace(child, state / child.name)
-                lifted["lifted_from_nested_layout"] = "true"
-        if _is_empty_dir(nested_state):
-            nested_state.rmdir()
+        merge_dir_into(nested_state, state, aside_name=f"{STATE_SUBDIR}.before-prepare-{stamp}")
+        lifted["lifted_from_nested_layout"] = "true"
     nested_link = state / LINK_SUBDIR
     if nested_link.is_dir():
         target = root / LINK_SUBDIR
-        if not target.exists() or _is_empty_dir(target):
+        if target.exists() and not _is_empty_dir(target):
+            merge_dir_into(nested_link, target, aside_name=f"{LINK_SUBDIR}.before-prepare-{stamp}")
+        else:
             if target.exists():
                 target.rmdir()
             os.replace(nested_link, target)
-            lifted["lifted_from_nested_layout"] = "true"
+        lifted["lifted_from_nested_layout"] = "true"
     return lifted
 
 
@@ -223,7 +349,24 @@ def diagnose() -> Dict[str, object]:
         for aside in sorted(runtime.parent.glob(f"{runtime.name}.before-prepare-*")) if runtime.parent.is_dir() else []:
             findings.append({"kind": "runtime_copy_kept_aside", "path": str(aside), "severity": "info"})
 
+    configured = configured_root()
+    if configured is not None:
+        try:
+            expected = normalized_root(configured) / STATE_SUBDIR
+        except PrepareError:
+            expected = None
+        applied = bool(
+            expected is not None and state_info["linked_to"]
+            and Path(str(state_info["linked_to"])) == expected.resolve()
+        )
+        if not applied:
+            problems = True
+            findings.append({
+                "kind": "configured_root_not_applied", "path": str(state), "severity": "problem",
+            })
+            root_hint = root_hint or configured
     return {
+        "configured_root": configured,
         "state": state_info,
         "link_sign_in": link_info,
         "findings": findings,
@@ -232,3 +375,24 @@ def diagnose() -> Dict[str, object]:
             f"booking-agent runtime prepare --persistent-root {root_hint}" if problems and root_hint else None
         ),
     }
+
+
+def configured_root() -> Optional[str]:
+    """The persistent folder a host names with ``BOOKING_AGENT_PERSISTENT_ROOT``, if any."""
+    value = (settings.get(ROOT_ENV) or "").strip()
+    return value or None
+
+
+def auto_prepare() -> Optional[List[Dict[str, str]]]:
+    """Link state into the host-named persistent folder, quietly and idempotently.
+
+    Nothing happens unless the host set ``BOOKING_AGENT_PERSISTENT_ROOT``. A failure never
+    blocks a booking; ``runtime doctor`` reports it.
+    """
+    root = configured_root()
+    if root is None:
+        return None
+    try:
+        return prepare(root, [])
+    except (PrepareError, OSError):
+        return None

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/tests/integration/test_regression_index.py

@@ -14,10 +14,17 @@ REGRESSIONS = {
     "state split across two persistent roots": [
         ("test_runtime_prepare.py", "test_a_root_already_named_booking_agent_is_not_nested_again"),
         ("test_runtime_prepare.py", "test_moving_to_a_different_root_brings_the_saved_state_along"),
-        ("test_runtime_prepare.py", "test_moving_to_a_root_that_has_its_own_state_leaves_the_old_one_untouched"),
+        ("test_runtime_prepare.py", "test_moving_to_a_root_that_has_its_own_state_merges_both"),
         ("test_runtime_prepare.py", "test_a_state_folder_nested_by_the_old_layout_is_lifted_back_up"),
         ("test_runtime_prepare.py", "test_doctor_reports_where_state_lives_and_what_is_orphaned"),
     ],
+    "restored booking files hidden behind a stale top-level copy (hosted layout)": [
+        ("test_runtime_prepare.py", "test_the_recorded_hosted_layout_is_repaired_without_losing_the_real_booking"),
+        ("test_runtime_prepare.py", "test_the_further_along_copy_of_a_session_wins_and_no_booking_is_lost"),
+    ],
+    "assistant had to remember to set up persistence": [
+        ("test_runtime_prepare.py", "test_the_named_persistent_folder_is_prepared_before_any_command"),
+    ],
     "sign-in approved but the poll never reported, so the user is asked again": [
         ("test_link_auth.py", "test_buyer_resolve_trusts_link_when_the_sign_in_poll_never_reported"),
     ],

{booking_agent_cli-0.5.0 → booking_agent_cli-0.6.0}/tests/integration/test_runtime_prepare.py

@@ -66,19 +66,23 @@ def test_moves_existing_contents_and_keeps_their_modes(runner, dirs):
     assert (link_dir / "config.json").read_text() == "{}"
 
 
-def test_keeps_the_runtime_copy_aside_when_both_hold_data(runner, dirs):
+def test_merges_when_both_hold_data_and_keeps_the_older_file_aside(runner, dirs):
     _home, root, link_dir = dirs
     (root / "link-cli").mkdir(parents=True)
-    (root / "link-cli" / "config.json").write_text("persistent")
+    (root / "link-cli" / "config.json").write_text("older")
     link_dir.mkdir(parents=True)
-    (link_dir / "config.json").write_text("runtime")
+    (link_dir / "config.json").write_text("newer")
+    (link_dir / "extra.json").write_text("only-here")
+    os.utime(root / "link-cli" / "config.json", (1_000, 1_000))
+    os.utime(link_dir / "config.json", (2_000, 2_000))
 
     result, body = _run(runner, "--persistent-root", str(root))
 
     assert result.exit_code == 0, result.stdout
-    assert (link_dir / "config.json").read_text() == "persistent"
-    aside = body["data"]["links"][1]["kept_runtime_copy_at"]
-    assert open(os.path.join(aside, "config.json")).read() == "runtime"
+    assert (link_dir / "config.json").read_text() == "newer"
+    assert (link_dir / "extra.json").read_text() == "only-here"
+    aside = body["data"]["links"][1]["older_copies_kept_at"]
+    assert open(os.path.join(aside, "config.json")).read() == "older"
 
 
 def test_extra_links_resolve_relative_paths_under_the_root(runner, dirs, tmp_path):
@@ -187,19 +191,23 @@ def test_moving_to_a_different_root_brings_the_saved_state_along(runner, dirs, t
     assert [link["result"] for link in body["data"]["links"]][:2] == ["relinked", "relinked"]
 
 
-def test_moving_to_a_root_that_has_its_own_state_leaves_the_old_one_untouched(runner, dirs, tmp_path):
+def test_moving_to_a_root_that_has_its_own_state_merges_both(runner, dirs, tmp_path):
     home, root, link_dir = dirs
     _run(runner, "--persistent-root", str(root))
     (root / "link-cli" / "config.json").write_text("old-sign-in")
+    (root / "link-cli" / "only-old.json").write_text("kept")
+    os.utime(root / "link-cli" / "config.json", (1_000, 1_000))
     other = tmp_path / "other-keep"
     _seed(other / "booking-agent", other / "link-cli", session="newer", link="new-sign-in")
+    os.utime(other / "link-cli" / "config.json", (2_000, 2_000))
 
     result, body = _run(runner, "--persistent-root", str(other))
 
     assert result.exit_code == 0, result.stdout
     assert (link_dir / "config.json").read_text() == "new-sign-in"
-    assert (root / "link-cli" / "config.json").read_text() == "old-sign-in"
-    assert body["data"]["links"][1]["previous_root_left_at"] == str((root / "link-cli").resolve())
+    assert (link_dir / "only-old.json").read_text() == "kept"
+    assert body["data"]["links"][1]["merged_existing_contents"] == "true"
+    assert not (root / "link-cli").exists()
 
 
 def test_doctor_reports_where_state_lives_and_what_is_orphaned(runner, dirs, tmp_path):
@@ -228,3 +236,89 @@ def test_doctor_is_quiet_when_everything_is_in_one_place(runner, dirs):
     assert result.exit_code == 0, result.stdout
     assert body["data"]["healthy"] is True
     assert body["data"]["findings"] == []
+
+
+# --- Two booking files from different times are merged, never one hiding the other ---------------
+
+def _store(*sessions, active=None, created=None):
+    return {
+        "schema_version": 2, "sessions_created": created or len(sessions),
+        "active_session_id": active, "sessions": list(sessions),
+    }
+
+
+def test_the_further_along_copy_of_a_session_wins_and_no_booking_is_lost():
+    stale = {"id": "s1", "flow_phase": "INIT"}
+    real = {"id": "s1", "flow_phase": "CONFIRMED", "booking": {"id": "b1"}}
+    other = {"id": "s2", "flow_phase": "PREREQ_OK"}
+    merged = runtime_prepare.merge_session_stores(
+        _store(stale, active="s1"), _store(real, other, active="s2"),
+    )
+    by_id = {s["id"]: s for s in merged["sessions"]}
+    assert by_id["s1"]["flow_phase"] == "CONFIRMED" and by_id["s1"]["booking"] == {"id": "b1"}
+    assert set(by_id) == {"s1", "s2"}
+    assert merged["active_session_id"] == "s1"
+
+
+def test_the_recorded_hosted_layout_is_repaired_without_losing_the_real_booking(runner, dirs):
+    """A stale INIT store at the top level, the real one nested, a fresh store from today in /root."""
+    home, root, link_dir = dirs
+    state = root / "booking-agent"
+    state.mkdir(parents=True)
+    (state / ".usp-session.json").write_text(json.dumps(_store({"id": "run1", "flow_phase": "INIT"})))
+    nested = state / "booking-agent"
+    nested.mkdir()
+    (nested / ".usp-session.json").write_text(json.dumps(_store(
+        {"id": "run1", "flow_phase": "PAYMENT_PENDING"}, {"id": "run1b", "flow_phase": "CONFIRMED"},
+    )))
+    (state / "link-cli").mkdir()
+    (state / "link-cli" / "config.json").write_text("nested-link")
+    live = home / ".booking-agent"
+    live.mkdir()
+    (live / ".usp-session.json").write_text(json.dumps(_store({"id": "today", "flow_phase": "CONFIRMED"})))
+
+    result, _body = _run(runner, "--persistent-root", str(root))
+
+    assert result.exit_code == 0, result.stdout
+    merged = json.loads((home / ".booking-agent" / ".usp-session.json").read_text())
+    phases = {s["id"]: s["flow_phase"] for s in merged["sessions"]}
+    assert phases == {"run1": "PAYMENT_PENDING", "run1b": "CONFIRMED", "today": "CONFIRMED"}
+    assert (link_dir / "config.json").read_text() == "nested-link"
+    assert not (state / "booking-agent").exists() and not (state / "link-cli").exists()
+
+
+# --- A host that names its persistent folder needs no instruction from the assistant ------------
+
+def test_the_named_persistent_folder_is_prepared_before_any_command(runner, dirs, monkeypatch):
+    home, root, link_dir = dirs
+    monkeypatch.setenv("BOOKING_AGENT_PERSISTENT_ROOT", str(root))
+
+    result = runner.invoke(app, ["flow", "sessions", "list"])
+
+    assert result.exit_code == 0, result.stdout
+    assert (home / ".booking-agent").is_symlink()
+    assert (home / ".booking-agent").resolve() == (root / "booking-agent").resolve()
+    assert link_dir.resolve() == (root / "link-cli").resolve()
+
+
+def test_without_the_variable_nothing_is_linked(runner, dirs):
+    home, _root, _link_dir = dirs
+    runner.invoke(app, ["flow", "sessions", "list"])
+    assert not (home / ".booking-agent").is_symlink()
+
+
+def test_a_bad_persistent_folder_never_blocks_a_command(runner, dirs, monkeypatch):
+    monkeypatch.setenv("BOOKING_AGENT_PERSISTENT_ROOT", "relative/path")
+    result = runner.invoke(app, ["flow", "sessions", "list"])
+    assert result.exit_code == 0, result.stdout
+
+
+def test_doctor_flags_a_named_folder_the_state_is_not_in(runner, dirs, monkeypatch):
+    _home, root, _link_dir = dirs
+    monkeypatch.setenv("BOOKING_AGENT_PERSISTENT_ROOT", str(root))
+
+    body = json.loads(runner.invoke(app, ["runtime", "doctor"]).stdout)
+
+    assert body["data"]["healthy"] is False
+    assert {f["kind"] for f in body["data"]["findings"]} >= {"configured_root_not_applied"}
+    assert body["next_command"] == f"booking-agent runtime prepare --persistent-root {root}"