feat: opt-in by sync.json + per-instance ULID + restic subpath

Reshapes the launcher integration around two ideas:

  1. ONE global Prism PreLaunch/PostExit hook is enough for all
     instances. Wire it once at Settings > Default > Custom commands:

         python /opt/cloud-sync.pyz pull --pack-folder=$INST_MC_DIR
         python /opt/cloud-sync.pyz push --pack-folder=$INST_MC_DIR

     Instances WITHOUT .cloud-sync/sync.json are silent no-ops (rc=0,
     no UI, no banner). The opt-in probe runs BEFORE the UI factory
     so Prism's launch log stays clean for non-sync instances.

  2. Per-instance opt-in via 'setup' / 'init' subcommands that mint a
     fresh ULID-style instance_id + write sync.json (mode 644) and
     token (mode 600). 'disable' removes sync.json; cloud data
     untouched.

Restic URL gains an /<instance_id>/ subpath under the user's
namespace, so two Prism instances of the same Discord user no longer
share a snapshot timeline. --private-repos still gates on the first
path segment (the username); deeper segments are user-controlled,
so this works without server-side coordination. First-push-on-a-new-
instance probes via 'restic cat config' and 'init's the per-instance
repo if absent.

UI label resolution is runtime-only (NEVER stored in sync.json) so
the user renaming the Prism instance just propagates through on
next launch:

    --instance-label  >  $INST_NAME  >  $INST_ID  >  instance_id[:8]

Schema bumps:
  state.json schema: 1 -> 2, adds instance_id field. Schema-1 files
  are treated as missing (existing test1 user re-pulls fresh).
  sync.json schema: 1 (new file).

CLI rework:
  pull / push   no --url; load everything from sync.json
  setup         interactive: Qt login dialog for token; URL prompt
                if --url omitted; falls back to stdin when headless
  init          non-interactive setup; for scripted callers
  disable       rm sync.json

Args dataclass: drops 'url', adds 'instance_label'. cli.parse() now
returns (cmd, Namespace); a separate args_from(ns) builds the Args
so each subcommand can pluck the bits it needs from the Namespace
without forcing a 'one Args fits all subcommands' shape.

73 tests green; pyz 75 KB.

Smoke-verified locally:
  - pull/push on a folder without sync.json: silent rc=0, no banner
  - init writes sync.json (644) + token (600) with correct contents
  - disable removes sync.json, keeps token
  - mint produces unique 26-char base32 instance_ids
  - label resolution chain (flag > INST_NAME > INST_ID > prefix)

cloud_sync/cli.py

@@ -1,8 +1,22 @@
 """CLI parsing + entry point dispatch.
 
-Flag style mirrors packwiz-installer-bootstrap so operators wiring Prism's
-PreLaunch/PostExit hooks don't relearn the surface. Supports both
-``--url value`` and ``--url=value`` forms.
+Subcommands:
+
+  pull / push    Sync. No-op if ``<pack>/.cloud-sync/sync.json`` is missing.
+                 All settings (url, instance_id) read from sync.json — flags
+                 are for runtime tweaks only.
+  setup          Interactive opt-in: prompt URL + token, mint instance_id,
+                 write sync.json + token. Player runs this once per instance.
+  init           Non-interactive setup (scripted / CI).
+  disable        Remove sync.json. Re-noops the instance. Cloud data untouched.
+
+Global Prism wiring (paste-once into Settings → Custom commands):
+
+  PreLaunchCommand=python /opt/cloud-sync.pyz pull --pack-folder=$INST_MC_DIR
+  PostExitCommand=python  /opt/cloud-sync.pyz push --pack-folder=$INST_MC_DIR
+
+Instance opt-in is then per-instance via ``setup``; non-enabled instances
+launch normally without any sync work happening.
 """
 
 from __future__ import annotations
@@ -15,14 +29,16 @@ from pathlib import Path
 
 @dataclass(frozen=True)
 class Args:
-    """Parsed CLI args shared by both pull + push subcommands."""
+    """Parsed CLI args. ``url`` comes from sync.json at runtime for pull/push;
+    the CLI ``--url`` flag is only consulted by ``setup`` / ``init`` (recorded
+    once into sync.json)."""
 
-    url: str
     pack_folder: Path
     token_file: Path
     restic_binary: Path | None  # None → auto-discover
     allow_download: bool
     headless: bool
+    instance_label: str | None  # override; usually unset (env fallback)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -31,66 +47,128 @@ def build_parser() -> argparse.ArgumentParser:
         description="Per-user Minecraft instance sync via the Timemachine Network.",
     )
     p.add_argument("--version", action="version", version="instance-sync 0.1.0")
-
     sub = p.add_subparsers(dest="cmd", required=True)
+
+    # --- pull / push: shared flags, no required --url ---
     for name in ("pull", "push"):
         sp = sub.add_parser(name, help=f"{name} instance state")
-        sp.add_argument(
-            "--url", required=True,
-            help="Timemachine Network endpoint (e.g. https://cloud.tm.center)",
-        )
-        sp.add_argument(
-            "--pack-folder", default=".", type=Path,
-            help="Minecraft instance directory (default: cwd)",
-        )
-        sp.add_argument(
-            "--token-file", default=None, type=Path,
-            help="Token file path (default: <pack-folder>/.cloud-sync/token)",
-        )
-        sp.add_argument(
-            "--restic-binary", default=None, type=Path,
-            help="Path to a restic binary; overrides auto-discovery",
-        )
-        sp.add_argument(
-            "--no-download", action="store_true",
-            help="Don't auto-fetch restic from upstream; fail if not found locally",
-        )
-        sp.add_argument(
-            "-g", "--no-gui", action="store_true",
-            help="Headless mode (no Qt windows; status to stdout only)",
-        )
+        _add_runtime_args(sp)
+
+    # --- setup: interactive opt-in ---
+    sp = sub.add_parser(
+        "setup",
+        help="enable sync on this instance (interactive: prompt URL + token)",
+    )
+    _add_runtime_args(sp)
+    sp.add_argument(
+        "--url", default=None,
+        help="Timemachine Network endpoint (skips the prompt if given)",
+    )
+
+    # --- init: non-interactive setup ---
+    sp = sub.add_parser(
+        "init",
+        help="non-interactive equivalent of setup (for scripted / CI use)",
+    )
+    _add_runtime_args(sp)
+    sp.add_argument(
+        "--url", required=True,
+        help="Timemachine Network endpoint (required)",
+    )
+    sp.add_argument(
+        "--token", default=None,
+        help="discord_id:password token (read from stdin if omitted)",
+    )
+
+    # --- disable: rm sync.json ---
+    sp = sub.add_parser(
+        "disable",
+        help="remove sync.json — re-noops the instance. Cloud data untouched.",
+    )
+    sp.add_argument(
+        "--pack-folder", default=".", type=Path,
+        help="Minecraft instance directory (default: cwd)",
+    )
+
     return p
 
 
-def parse(argv: list[str]) -> tuple[str, Args]:
-    """Parse argv → (subcommand, Args). Raises SystemExit on error/help."""
+def _add_runtime_args(sp: argparse.ArgumentParser) -> None:
+    sp.add_argument(
+        "--pack-folder", default=".", type=Path,
+        help="Minecraft instance directory (default: cwd)",
+    )
+    sp.add_argument(
+        "--token-file", default=None, type=Path,
+        help="Token file path (default: <pack-folder>/.cloud-sync/token)",
+    )
+    sp.add_argument(
+        "--restic-binary", default=None, type=Path,
+        help="Path to a restic binary; overrides auto-discovery",
+    )
+    sp.add_argument(
+        "--no-download", action="store_true",
+        help="Don't auto-fetch restic from upstream; fail if not found locally",
+    )
+    sp.add_argument(
+        "-g", "--no-gui", action="store_true",
+        help="Headless mode (no Qt windows; status to stdout only)",
+    )
+    sp.add_argument(
+        "--instance-label", default=None,
+        help="Override the instance display name. Default: $INST_NAME from "
+             "Prism's env, then $INST_ID, then first 8 chars of instance_id.",
+    )
+
+
+def parse(argv: list[str]) -> tuple[str, argparse.Namespace]:
     ns = build_parser().parse_args(argv)
+    return ns.cmd, ns
+
+
+def args_from(ns: argparse.Namespace) -> Args:
+    """Convert argparse Namespace → Args dataclass. Centralizes path
+    normalization so subcommands don't each repeat the recipe."""
     pack = Path(ns.pack_folder).absolute().resolve()
     token = (
         Path(ns.token_file).absolute()
-        if ns.token_file is not None
+        if getattr(ns, "token_file", None) is not None
         else pack / ".cloud-sync" / "token"
     )
-    return ns.cmd, Args(
-        url=ns.url,
+    return Args(
         pack_folder=pack,
         token_file=token,
-        restic_binary=Path(ns.restic_binary).absolute() if ns.restic_binary else None,
-        allow_download=not ns.no_download,
-        headless=ns.no_gui,
+        restic_binary=Path(ns.restic_binary).absolute()
+        if getattr(ns, "restic_binary", None)
+        else None,
+        allow_download=not getattr(ns, "no_download", False),
+        headless=getattr(ns, "no_gui", False),
+        instance_label=getattr(ns, "instance_label", None),
     )
 
 
 def main(argv: list[str] | None = None) -> int:
     """CLI entrypoint. Returns exit code (0=ok, 1=user cancel, 2=error)."""
-    # Imports kept here so tests of parse() don't drag UI in.
+    # Lazy imports keep tests of parse() isolated from UI deps.
     from . import sync, ui
 
     try:
-        cmd, args = parse(sys.argv[1:] if argv is None else argv)
+        cmd, ns = parse(sys.argv[1:] if argv is None else argv)
     except SystemExit as e:
         return int(e.code) if isinstance(e.code, int) else 2
 
+    if cmd == "disable":
+        return _run_disable(ns)
+    if cmd in ("setup", "init"):
+        return _run_setup(ns, cmd)
+
+    # pull / push — opt-in gated on sync.json. We re-check here BEFORE
+    # spinning up the UI / printing any banner so non-sync-enabled
+    # instances launch in true silence (clean Prism log).
+    args = args_from(ns)
+    from . import config as cfgmod
+    if not cfgmod.exists(args.pack_folder):
+        return 0
     action = {"pull": sync.pull, "push": sync.push}[cmd]
     progress = ui.make_progress(headless=args.headless)
     title = "Instance sync — pulling" if cmd == "pull" else "Instance sync — pushing"
@@ -103,3 +181,28 @@ def main(argv: list[str] | None = None) -> int:
     except Exception as e:  # noqa: BLE001
         print(f"instance-sync {cmd}: {e}", file=sys.stderr)
         return 2
+
+
+def _run_disable(ns: argparse.Namespace) -> int:
+    from . import config as cfgmod
+    pack = Path(ns.pack_folder).absolute().resolve()
+    if cfgmod.delete(pack):
+        print(f"instance-sync: removed {cfgmod.config_path(pack)}")
+    else:
+        print(f"instance-sync: no sync.json at {cfgmod.config_path(pack)} (already disabled)")
+    return 0
+
+
+def _run_setup(ns: argparse.Namespace, cmd: str) -> int:
+    """Wire `setup` (interactive) and `init` (flags-only) through the same
+    flow module so both share the dialog/CLI logic."""
+    from . import setup_flow
+    args = args_from(ns)
+    url = getattr(ns, "url", None)
+    token_override = getattr(ns, "token", None)
+    return setup_flow.run(
+        args=args,
+        url=url,
+        token=token_override,
+        interactive=(cmd == "setup"),
+    )

cloud_sync/config.py

@@ -0,0 +1,169 @@
+"""Per-instance sync.json — the opt-in marker + minimal config.
+
+If ``<pack-folder>/.cloud-sync/sync.json`` doesn't exist, the pyz is a
+no-op (PreLaunch hook returns 0, MC launches normally). Its presence
+opts the instance into sync; its contents tell the script where to sync
+to (`url`) and which restic sub-path to use (`instance_id`).
+
+Intentionally minimal: NO label (UI display name comes from
+``$INST_NAME`` / ``$INST_ID`` / ``--instance-label`` at runtime so the
+Prism rename flow Just Works), NO token (mode-600 ``token`` lives next
+to it), NO state (``state.json`` is separate, written by the sync flow).
+
+instance_id is a 26-char ULID-style string (timestamp + 80 random bits,
+base32, no padding) — sortable, URL-safe, no hyphens. Stable forever.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import platform
+import secrets
+import socket
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class SyncConfig:
+    url: str
+    instance_id: str
+    created_at: datetime
+    host_fingerprint: str
+
+
+def config_path(pack_folder: Path) -> Path:
+    return pack_folder / ".cloud-sync" / "sync.json"
+
+
+def exists(pack_folder: Path) -> bool:
+    """Cheap opt-in check used by ``pull`` / ``push`` before doing anything else."""
+    return config_path(pack_folder).exists()
+
+
+def read(pack_folder: Path) -> SyncConfig | None:
+    """Parse sync.json or return None if missing / corrupt / wrong schema."""
+    p = config_path(pack_folder)
+    if not p.exists():
+        return None
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if data.get("schema") != SCHEMA_VERSION:
+        return None
+    try:
+        return SyncConfig(
+            url=data["url"],
+            instance_id=data["instance_id"],
+            created_at=_parse_iso(data["created_at"]),
+            host_fingerprint=data.get("host_fingerprint", ""),
+        )
+    except (KeyError, ValueError):
+        return None
+
+
+def write(pack_folder: Path, cfg: SyncConfig) -> None:
+    """Persist sync.json (mode 644 — not a secret)."""
+    p = config_path(pack_folder)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "schema": SCHEMA_VERSION,
+        "url": cfg.url,
+        "instance_id": cfg.instance_id,
+        "created_at": cfg.created_at.astimezone(timezone.utc)
+        .isoformat()
+        .replace("+00:00", "Z"),
+        "host_fingerprint": cfg.host_fingerprint,
+    }
+    p.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    p.chmod(0o644)
+
+
+def delete(pack_folder: Path) -> bool:
+    """Remove sync.json. Used by the ``disable`` subcommand. Returns True if a
+    file was removed, False if nothing was there."""
+    p = config_path(pack_folder)
+    if not p.exists():
+        return False
+    p.unlink()
+    return True
+
+
+# ---------------------------------------------------------------------------
+# minting
+# ---------------------------------------------------------------------------
+
+
+def mint(url: str) -> SyncConfig:
+    """Build a fresh SyncConfig with a new ULID-style id and host fingerprint."""
+    return SyncConfig(
+        url=url,
+        instance_id=new_instance_id(),
+        created_at=datetime.now(timezone.utc),
+        host_fingerprint=_machine_fingerprint(),
+    )
+
+
+def new_instance_id() -> str:
+    """26-char base32 string: 6 bytes ms timestamp + 10 bytes random.
+
+    Like a ULID, minus the strict Crockford alphabet. Sortable by mint
+    time, URL-safe, no padding, no hyphens.
+    """
+    ms = int(time.time() * 1000).to_bytes(6, "big")
+    rand = secrets.token_bytes(10)
+    return base64.b32encode(ms + rand).decode("ascii").rstrip("=")
+
+
+def _machine_fingerprint() -> str:
+    """sha256 of (hostname || node || nanosecond timestamp), first 16 hex chars.
+
+    Not a cryptographic identity — just a hint we can compare across pulls
+    to detect "this instance was first set up on a different machine"
+    cases later. Don't use it for authz.
+    """
+    src = f"{platform.node()}:{socket.gethostname()}:{time.time_ns()}"
+    return hashlib.sha256(src.encode()).hexdigest()[:16]
+
+
+def _parse_iso(s: str) -> datetime:
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+    dt = datetime.fromisoformat(s)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# display label resolution (NOT stored — derived per-run)
+# ---------------------------------------------------------------------------
+
+
+def resolve_label(flag_label: str | None, instance_id: str) -> str:
+    """Pick the UI display name for an instance.
+
+    Precedence:
+      1. ``--instance-label`` CLI flag (explicit override)
+      2. ``$INST_NAME`` (Prism's rename-tracking display name)
+      3. ``$INST_ID`` (Prism's stable folder name)
+      4. first 8 chars of the instance_id (last-resort)
+
+    Never stored on disk — recomputed every run so Prism renames flow
+    through naturally.
+    """
+    if flag_label:
+        return flag_label
+    env = os.environ.get("INST_NAME") or os.environ.get("INST_ID")
+    if env:
+        return env
+    return instance_id[:8]

cloud_sync/setup_flow.py

@@ -0,0 +1,123 @@
+"""Interactive (``setup``) + non-interactive (``init``) opt-in flow.
+
+Both end up doing the same thing — write a fresh sync.json + token to
+``<pack>/.cloud-sync/``. Difference is just how the URL + token get
+collected:
+
+  setup      Qt login dialog for token; URL prompted at stdin if not
+             supplied via ``--url`` flag. Falls back to all-stdin when
+             headless / Qt missing.
+  init       Both URL + token come from flags. No prompting. Suitable
+             for scripted CI runs or external launcher hooks (frazclient,
+             discord-bot ``/cloud register`` integration).
+
+This is the only path that creates sync.json; pull/push never auto-mint.
+That makes opt-in explicit — a player intentionally enables sync rather
+than being silently signed up the first time they launch an instance.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from . import config as cfgmod
+from .cli import Args
+
+
+def run(
+    args: Args,
+    url: str | None,
+    token: str | None,
+    interactive: bool,
+) -> int:
+    """Drive the opt-in flow. Returns CLI exit code (0/1/2)."""
+    pack = args.pack_folder
+    cfg_path = cfgmod.config_path(pack)
+
+    if cfgmod.exists(pack):
+        existing = cfgmod.read(pack)
+        if existing is not None:
+            print(
+                f"instance-sync: this instance is already sync-enabled\n"
+                f"  sync.json:   {cfg_path}\n"
+                f"  url:         {existing.url}\n"
+                f"  instance_id: {existing.instance_id}\n"
+                f"  created_at:  {existing.created_at}\n"
+                "Run with `disable` first if you want to re-enroll.",
+                file=sys.stderr,
+            )
+            return 2
+
+    if url is None:
+        if not interactive:
+            print(
+                "instance-sync: --url is required for `init`",
+                file=sys.stderr,
+            )
+            return 2
+        url = _prompt_url()
+        if not url:
+            return 1
+
+    if token is None:
+        token = _prompt_token(headless=args.headless or not interactive)
+        if token is None:
+            print("instance-sync: setup cancelled (no token)", file=sys.stderr)
+            return 1
+
+    if ":" not in token:
+        print(
+            "instance-sync: token must be discord_id:password",
+            file=sys.stderr,
+        )
+        return 2
+    head, _, tail = token.partition(":")
+    if not head.strip().isdigit() or not tail.strip():
+        print(
+            "instance-sync: token malformed (discord_id must be numeric, "
+            "password must be non-empty)",
+            file=sys.stderr,
+        )
+        return 2
+
+    cfg = cfgmod.mint(url=url.strip())
+    cfgmod.write(pack, cfg)
+
+    args.token_file.parent.mkdir(parents=True, exist_ok=True)
+    args.token_file.write_text(token.strip() + "\n", encoding="utf-8")
+    args.token_file.chmod(0o600)
+
+    print(
+        f"instance-sync: enabled\n"
+        f"  sync.json:   {cfg_path}\n"
+        f"  token:       {args.token_file}\n"
+        f"  url:         {cfg.url}\n"
+        f"  instance_id: {cfg.instance_id}"
+    )
+    return 0
+
+
+def _prompt_url() -> str:
+    """stdin prompt for the network endpoint."""
+    try:
+        v = input("Timemachine Network URL (e.g. https://cloud.tm.center): ").strip()
+        return v
+    except (EOFError, KeyboardInterrupt):
+        return ""
+
+
+def _prompt_token(headless: bool) -> str | None:
+    """Returns the discord_id:password token string, or None if user cancelled."""
+    if not headless:
+        try:
+            from .ui_qt import prompt_login_qt
+        except ImportError:
+            pass
+        else:
+            return prompt_login_qt()
+    # Headless fallback.
+    try:
+        return input("Paste token (discord_id:password): ").strip()
+    except (EOFError, KeyboardInterrupt):
+        return None

cloud_sync/state.py

@@ -17,11 +17,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 
 
 @dataclass(frozen=True)
 class State:
+    instance_id: str
     last_pulled_snapshot_id: str
     last_pulled_at: datetime
     host_tag: str = "instance-sync"
@@ -44,6 +45,7 @@ def read(pack_folder: Path) -> State | None:
         return None
     try:
         return State(
+            instance_id=data["instance_id"],
             last_pulled_snapshot_id=data["last_pulled_snapshot_id"],
             last_pulled_at=_parse_iso(data["last_pulled_at"]),
             host_tag=data.get("host_tag", "instance-sync"),
@@ -58,6 +60,7 @@ def write(pack_folder: Path, state: State) -> None:
     p.parent.mkdir(parents=True, exist_ok=True)
     payload = {
         "schema": SCHEMA_VERSION,
+        "instance_id": state.instance_id,
         "last_pulled_snapshot_id": state.last_pulled_snapshot_id,
         "last_pulled_at": state.last_pulled_at.astimezone(timezone.utc)
         .isoformat()

cloud_sync/sync.py

@@ -30,7 +30,7 @@ import urllib.parse
 from datetime import datetime, timezone
 from pathlib import Path
 
-from . import restic, scope as scopemod, state as statemod
+from . import config as cfgmod, restic, scope as scopemod, state as statemod
 from .cli import Args
 from .creds import read_credentials
 from .ui import HeadlessProgress, Progress
@@ -39,11 +39,18 @@ from .ui import HeadlessProgress, Progress
 def pull(args: Args, progress: Progress | None = None) -> int:
     ui = progress or HeadlessProgress()
 
-    # First-run login. If the user declines, skip cloud sync without
-    # blocking the launch (return 0 — non-fatal for Prism PreLaunch).
+    # Opt-in gate: no sync.json → instance isn't sync-enabled, silent no-op.
+    # This is the path the global Prism PreLaunch hook takes for instances
+    # the player hasn't opted into sync.
+    sync_cfg = cfgmod.read(args.pack_folder)
+    if sync_cfg is None:
+        return 0
+
+    # First-run login. If the user declines, skip without blocking the
+    # launch (return 0 — non-fatal for Prism PreLaunch).
     if not args.token_file.exists():
         if not _prompt_login_and_save(args, ui):
-            ui.set_status("Cloud sync skipped")
+            ui.set_status("Sync skipped")
             print("instance-sync: no token; skipping pull")
             return 0
 
@@ -52,8 +59,9 @@ def pull(args: Args, progress: Progress | None = None) -> int:
 
     ui.set_status("Resolving restic binary…")
     binary = restic.resolve_binary(args)
-    repo = _restic_repo(args.url, discord_id, password)
+    repo = _restic_repo(sync_cfg.url, discord_id, password, sync_cfg.instance_id)
     env = _restic_env()
+    label = cfgmod.resolve_label(args.instance_label, sync_cfg.instance_id)
 
     ui.set_status("Checking remote snapshots…")
     code, out = restic.run(
@@ -99,7 +107,7 @@ def pull(args: Args, progress: Progress | None = None) -> int:
         if not modified:
             decision = "use_remote"
         else:
-            decision = _ask_conflict(modified, remote_time)
+            decision = _ask_conflict(modified, remote_time, label)
             if decision is None:
                 # UI unavailable in headless mode → conservative: cancel
                 ui.set_status("Conflict detected; no UI available")
@@ -141,6 +149,7 @@ def pull(args: Args, progress: Progress | None = None) -> int:
     statemod.write(
         args.pack_folder,
         statemod.State(
+            instance_id=sync_cfg.instance_id,
             last_pulled_snapshot_id=remote_id,
             last_pulled_at=datetime.now(timezone.utc),
         ),
@@ -153,8 +162,13 @@ def pull(args: Args, progress: Progress | None = None) -> int:
 def push(args: Args, progress: Progress | None = None) -> int:
     ui = progress or HeadlessProgress()
 
+    # Opt-in gate — see pull().
+    sync_cfg = cfgmod.read(args.pack_folder)
+    if sync_cfg is None:
+        return 0
+
     if not args.token_file.exists():
-        ui.set_status("No network token; skipping push")
+        ui.set_status("No token; skipping push")
         print("instance-sync: no token; skipping push")
         return 0
 
@@ -163,9 +177,15 @@ def push(args: Args, progress: Progress | None = None) -> int:
 
     ui.set_status("Resolving restic binary…")
     binary = restic.resolve_binary(args)
-    repo = _restic_repo(args.url, discord_id, password)
+    repo = _restic_repo(sync_cfg.url, discord_id, password, sync_cfg.instance_id)
     env = _restic_env()
 
+    # First-push-on-a-new-instance: probe + init if the per-instance repo
+    # doesn't exist yet. Idempotent on subsequent pushes.
+    code = _ensure_repo_initialized(binary, repo, env, ui)
+    if code != 0:
+        return code
+
     scope = scopemod.load(args.pack_folder)
     files_from, exclude_from = scopemod.materialize_for_restic(args.pack_folder, scope)
 
@@ -196,6 +216,7 @@ def push(args: Args, progress: Progress | None = None) -> int:
         statemod.write(
             args.pack_folder,
             statemod.State(
+                instance_id=sync_cfg.instance_id,
                 last_pulled_snapshot_id=new_id,
                 last_pulled_at=datetime.now(timezone.utc),
             ),
@@ -290,6 +311,7 @@ def _matches_any(rel: Path, patterns: list[str]) -> bool:
 def _ask_conflict(
     modified: list[tuple[Path, datetime]],
     remote_time: datetime,
+    label: str,
 ) -> str | None:
     """Show the conflict dialog. Returns choice or None if no UI available."""
     try:
@@ -300,7 +322,7 @@ def _ask_conflict(
     return prompt_conflict_qt(
         local_modified=_format_dt(newest[1]),
         remote_modified=_format_dt(remote_time),
-        save_label="Minecraft save",
+        save_label=label,
     )
 
 
@@ -394,7 +416,16 @@ def _format_dt(dt: datetime) -> str:
     return f"{weekday}, {month} {local.day}, {local.year} at {hour}:{local.minute:02d} {ampm}"
 
 
-def _restic_repo(base_url: str, discord_id: str, password: str) -> str:
+def _restic_repo(
+    base_url: str, discord_id: str, password: str, instance_id: str
+) -> str:
+    """Build ``rest:<scheme>://<id>:<pw>@<host>/<id>/<instance_id>/``.
+
+    Per-instance subpath under the user's namespace. ``--private-repos``
+    on restic-rest-server only enforces the FIRST path segment (the
+    username); deeper segments are user-controlled, so each instance
+    gets its own isolated restic repo without server-side coordination.
+    """
     raw = base_url.strip()
     if raw.startswith("rest:"):
         raw = raw[len("rest:"):]
@@ -402,13 +433,50 @@ def _restic_repo(base_url: str, discord_id: str, password: str) -> str:
     scheme_end = raw.find("://")
     if scheme_end <= 0:
         raise ValueError(
-            f"--url must include scheme (http:// or https://): {base_url!r}"
+            f"url must include scheme (http:// or https://): {base_url!r}"
         )
     scheme = raw[: scheme_end + 3]
     host_and_path = raw[scheme_end + 3 :]
     u = urllib.parse.quote(discord_id, safe="")
     p = urllib.parse.quote(password, safe="")
-    return f"rest:{scheme}{u}:{p}@{host_and_path}/{discord_id}/"
+    iid = urllib.parse.quote(instance_id, safe="")
+    return f"rest:{scheme}{u}:{p}@{host_and_path}/{discord_id}/{iid}/"
+
+
+def _ensure_repo_initialized(
+    binary: Path, repo: str, env: dict[str, str], ui: "Progress"
+) -> int:
+    """`restic cat config` to probe; `restic init` if absent. Returns 0/1/2.
+
+    Cheap to call before every push — `cat config` is a single HTTP GET.
+    Idempotent: if the repo already exists, init is skipped.
+    """
+    code, _ = restic.run(
+        binary,
+        ["-r", repo, "--insecure-no-password", "cat", "config"],
+        env=env,
+        cancel_check=ui.is_cancelled,
+    )
+    if code == 0:
+        return 0
+    if code == -1:
+        return 1
+    # cat config failed → assume not initialized; init it.
+    ui.set_status("Initializing remote repo…")
+    code, _ = restic.run(
+        binary,
+        ["-r", repo, "--insecure-no-password", "init"],
+        env=env,
+        cancel_check=ui.is_cancelled,
+    )
+    if code == -1:
+        return 1
+    if code != 0:
+        print(
+            f"instance-sync: restic init failed (exit {code})", file=sys.stderr
+        )
+        return 2
+    return 0
 
 
 def _restic_env() -> dict[str, str]: