@junghanacs/entwurf 0.15.0 → 0.16.0

package/scripts/register-pi-package.py

@@ -51,7 +51,53 @@ This wiring (user scope) dropped when `pi install` was removed from setup
 lets run.sh (both scopes + remove) and smoke-user-scope-citizen share ONE
 implementation — mirrors the meta-bridge-state.py split.
 
-Usage: register-pi-package.py <settings.json> <repo_dir> [--remove]
+USER-SCOPE OWNERSHIP (#86 C2). `--scope user --state <path>` puts the GLOBAL
+packages[] entry under a recorded owner (`packageRoot` in
+$XDG_DATA_HOME/entwurf/pi-package/install-state.json) and retires the silent
+last-writer-wins normalization for that scope. Once an owner is recorded, EVERY
+recorded-owner operation (install / takeover / inverse / doctor, preflight and
+writer alike) judges the settings through ONE bounded exact-owner classifier:
+the owner must hold exactly ONE exact entry (the resolved absolute path, or a
+settings-relative path resolving exactly there) and there must be NO additional
+entwurf-shaped root. A missing, duplicated, or extra root is a named zero-write
+refusal (exit 6) — user scope never routes through the broad project-scope
+`register()` collapse, which would delete another root's entry as collateral:
+  - fresh (no state, no entwurf entry)     → append exact entry + write owner state;
+  - same root (state.packageRoot == root)  → classifier holds → no-op (bytes/mtime
+                                              stable); classifier violated → refuse;
+  - legacy no-state, sole entry EXACTLY this root (absolute or settings-relative)
+                                            → ADOPTION: state written, settings
+                                              bytes/mtime untouched;
+  - legacy no-state, any other/ambiguous entwurf shape → REFUSE (exit 6), zero write;
+  - state owned by ANOTHER root, live OR missing → normal install REFUSE (exit 6),
+    zero write, naming `takeover-user-scope`; a missing owner additionally shows as
+    the doctor verdict `missing-owner`;
+  - the ONLY writer that replaces another owner is the operator-explicit
+    `--takeover` (run.sh takeover-user-scope): the recorded owner's EXACT entry is
+    replaced in place (old→new, both roots reported). Takeover licenses moving THE
+    registration, never collateral deletion — an ambiguous store refuses. With no
+    recorded owner it claims a SINGLE legacy entwurf-shaped entry; two or more are
+    ambiguous and refuse.
+Remove under user scope is same-owner-only and exact-entry-only: a live foreign
+owner refuses; a MISSING owner is removable only through run.sh's aligned orphan
+path (`--orphan-cleanup`, passed after package entry + package state + provider
+installerRoot all agree on that same missing root). No --force flag exists.
+`--doctor` reports unregistered / owned / legacy-no-state / mismatch /
+foreign-owner(live) / missing-owner without writing; its owner judgment asks the
+SAME exact classifier, so a store the inverse would refuse can never read green.
+PROJECT scope keeps the state-less behavior above.
+
+`--preflight` (user scope) runs the SAME ownership decision READ-ONLY: identical
+exit codes, zero writes — run.sh completes both the package and provider
+preflights before either writer runs, so a refusal on one side leaves the other
+side byte-identical (atomic user-scope operations). `--doctor` additionally takes
+`--provider-state <path>` to report a packageRoot↔installerRoot coupling mismatch
+as FAIL (ownership coupling only; provider runtime stays with doctor-pi-provider).
+
+Usage: register-pi-package.py <settings.json> <repo_dir> [--remove] [--dry-run]
+         [--scope user|project] [--state <path>] [--takeover] [--orphan-cleanup]
+         [--doctor] [--preflight] [--provider-state <path>]
+Exit codes: 0 ok · 3 refuse-symlink · 4 corrupt-state/settings · 6 ownership-refusal.
 """
 
 from __future__ import annotations
@@ -68,7 +114,7 @@ from pathlib import Path
 # script is run by path, which is how run.sh and every gate invoke it; the explicit
 # insert keeps the import true under any other invocation form.
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from pi_settings_io import detect_indent, dumps  # noqa: E402
+from pi_settings_io import classify_installer_root, detect_indent, dumps  # noqa: E402
 
 # A leading `<scheme>:` means the string is a package SPEC (npm:, git:, https:),
 # never a filesystem path — so it is never resolved against the settings dir.
@@ -278,15 +324,474 @@ def would_remove(settings_path: Path, repo_dir_arg: str) -> tuple[int, int]:
     return len(removable), len(preserved)
 
 
+# ── user-scope ownership (#86 C2) ────────────────────────────────────────────
+STATE_SCHEMA_VERSION = 1
+
+
+def _refuse(code: int, msg: str) -> None:
+    sys.stderr.write(msg.rstrip("\n") + "\n")
+    raise SystemExit(code)
+
+
+def _refuse_symlink(settings_path: Path) -> None:
+    # The package writer must never follow a foreign symlink into someone else's
+    # SSOT — same rule (and exit code) as register-pi-provider, checked BEFORE
+    # any provider step can refuse for its own reasons.
+    if settings_path.is_symlink():
+        _refuse(3, f"register-pi-package: refusing to write through {settings_path} — it is a symlink "
+                   "(someone else's SSOT). Manage it there, or replace it with a regular file, then retry.")
+
+
+def _load_state(state_path: Path) -> dict | None:
+    if not state_path.exists():
+        return None
+    try:
+        data = json.loads(state_path.read_text())
+    except json.JSONDecodeError as err:
+        _refuse(4, f"register-pi-package: install-state {state_path} is not valid JSON: {err}")
+    if not isinstance(data, dict) or not isinstance(data.get("packageRoot"), str):
+        _refuse(4, f"register-pi-package: install-state {state_path} has no packageRoot")
+    return data
+
+
+def _write_state(state_path: Path, repo_dir: str, settings_path: Path) -> None:
+    import datetime
+
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    state = {
+        "schemaVersion": STATE_SCHEMA_VERSION,
+        "packageRoot": repo_dir,
+        "managedSettingsPath": str(settings_path.resolve()),
+        "installedAt": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    tmp = state_path.with_name(state_path.name + f".tmp-{os.getpid()}")
+    tmp.write_text(json.dumps(state, indent=2) + "\n")
+    os.replace(tmp, state_path)
+
+
+def _sole_exact_self_entry(settings_path: Path, repo_dir: str) -> bool:
+    """True iff the settings carry exactly ONE entwurf entry and it names THIS root
+    exactly (canonical absolute or settings-relative self) — the only legacy
+    no-state shape adoption may claim without asking the operator."""
+    data = _load(settings_path) if settings_path.exists() else {}
+    packages = _packages(settings_path, data)
+    settings_dir = _settings_dir(settings_path)
+    matches = _entwurf_matches(packages, repo_dir, settings_dir)
+    return (
+        len(matches) == 1
+        and isinstance(matches[0], str)
+        and (matches[0] == repo_dir or is_settings_relative_self(matches[0], settings_dir, repo_dir))
+    )
+
+
+def _has_entwurf_entries(settings_path: Path, repo_dir: str) -> bool:
+    data = _load(settings_path) if settings_path.exists() else {}
+    packages = _packages(settings_path, data)
+    return bool(_entwurf_matches(packages, repo_dir, _settings_dir(settings_path)))
+
+
+def _check_settings_binding(state: dict, settings_path: Path, state_path: Path) -> None:
+    """The ownership state names WHICH settings file it manages. Any user-scope
+    operation targeting a DIFFERENT file is an ownership mismatch — fail closed
+    BEFORE either writer runs (this state is #86 C2 new; no legacy exemption)."""
+    managed = state.get("managedSettingsPath")
+    if not isinstance(managed, str):
+        _refuse(4, f"register-pi-package: install-state {state_path} has no managedSettingsPath string")
+    if os.path.abspath(managed) != os.path.abspath(str(settings_path)):
+        _refuse(6, f"register-pi-package: install-state {state_path} manages {managed}, but this operation "
+                   f"targets {settings_path} — ownership record and target disagree; zero settings bytes written. "
+                   "Inspect with './run.sh doctor-pi-package'.")
+
+
+def _classify_user_owner_entries(settings_path: Path, owner: str) -> tuple[list, list]:
+    """THE bounded exact-owner classifier (#86 C2 corrective amendment, B blockers 1+2).
+
+    Returns (exact, extra) for the recorded user-scope owner:
+      exact  packages[] STRING entries naming `owner` EXACTLY — the resolved absolute
+             path, or a settings-relative path resolving exactly there. Deliberately
+             narrower than is_entwurf_source: an owner operation must never reach an
+             npm spec or an unrelated `.../entwurf` path merely because the broad
+             matcher would.
+      extra  every OTHER entwurf-shaped entry (any shape) — with a recorded owner,
+             a second Entwurf-shaped root is AMBIGUITY, never collateral that
+             install/takeover/inverse may collapse or that the doctor may bless.
+
+    Every recorded-owner judgment (install, takeover, inverse, doctor, preflight and
+    writer alike) asks THIS function, so the verdicts cannot drift apart the way the
+    broad-install/exact-inverse split did.
+    """
+    data = _load(settings_path) if settings_path.exists() else {}
+    packages = _packages(settings_path, data)
+    settings_dir = _settings_dir(settings_path)
+    exact = [
+        p for p in packages
+        if isinstance(p, str) and (p.rstrip("/") == owner or is_settings_relative_self(p, settings_dir, owner))
+    ]
+    shaped = _entwurf_matches(packages, owner, settings_dir)
+    extra = [item for item in shaped if item not in exact]
+    return exact, extra
+
+
+def _require_user_owner_entry(settings_path: Path, owner: str) -> object:
+    """The refusing form of the classifier: exactly one exact entry, no extra
+    entwurf-shaped root — anything else is a named zero-write refusal (exit 6).
+    Returns the single exact entry."""
+    exact, extra = _classify_user_owner_entries(settings_path, owner)
+    if len(exact) != 1 or extra:
+        _refuse(6, f"register-pi-package: the recorded owner {owner} has {len(exact)} exact packages[] "
+                   f"entr{'y' if len(exact) == 1 else 'ies'} (expected exactly one) and {len(extra)} additional "
+                   f"entwurf-shaped entr{'y' if len(extra) == 1 else 'ies'} (expected none) — the ownership "
+                   "record and the settings are ambiguous; zero settings bytes written. "
+                   "Inspect with './run.sh doctor-pi-package'.")
+    return exact[0]
+
+
+def _replace_packages_entry(settings_path: Path, old_item: object, replacement: str) -> None:
+    """Swap ONE packages[] entry in place (first occurrence), preserving order,
+    every other entry, and the file's own indent unit."""
+    original_text = _read_text(settings_path)
+    data = _load(settings_path)
+    packages = _packages(settings_path, data)
+    swapped = False
+    out = []
+    for item in packages:
+        if not swapped and item == old_item:
+            out.append(replacement)
+            swapped = True
+        else:
+            out.append(item)
+    data["packages"] = out
+    _write(settings_path, data, original_text)
+
+
+def _remove_exact_owner_entry(settings_path: Path, owner: str) -> None:
+    """Remove the recorded owner's single classified exact entry — never through the
+    broad entwurf-shape matcher. An ambiguous store already refused upstream in
+    _require_user_owner_entry."""
+    exact = _require_user_owner_entry(settings_path, owner)
+    original_text = _read_text(settings_path)
+    data = _load(settings_path)
+    packages = _packages(settings_path, data)
+    removed = False
+    kept_pkgs = []
+    for item in packages:
+        if not removed and item == exact:
+            removed = True
+            continue
+        kept_pkgs.append(item)
+    data["packages"] = kept_pkgs
+    _write(settings_path, data, original_text)
+
+
+def register_user(settings_path: Path, repo_dir_arg: str, state_path: Path, takeover: bool,
+                  preflight: bool = False) -> int:
+    repo_dir = str(Path(repo_dir_arg).resolve())
+    _refuse_symlink(settings_path)
+    state = _load_state(state_path)
+    if state is not None:
+        _check_settings_binding(state, settings_path, state_path)
+
+    if state is not None and not takeover:
+        owner = state["packageRoot"]
+        if owner == repo_dir:
+            # Same-owner install NEVER routes through the broad register() collapse
+            # (#86 C2 corrective amendment, B blocker 1): with a recorded owner, the
+            # store either already holds exactly one exact entry with no other
+            # entwurf-shaped root — a no-op — or it is ambiguous and refuses. Another
+            # root's entry is never collateral a normal install may delete.
+            _require_user_owner_entry(settings_path, owner)
+            if preflight:
+                print("preflight: install ok (this root owns one unambiguous registration)")
+                return 0
+            print(f"install: entwurf package already registered (no-op) -> {repo_dir}")
+            return 0
+        if os.path.isdir(owner):
+            _refuse(6, "register-pi-package: the user-scope entwurf registration is owned by another LIVE root: "
+                       f"{owner}. Normal install/setup never replaces another owner — zero settings bytes written. "
+                       f"Run './run.sh takeover-user-scope' from {repo_dir} to explicitly move the shared entry.")
+        _refuse(6, "register-pi-package: the user-scope entwurf registration is owned by a MISSING root: "
+                   f"{owner} (doctor verdict: missing-owner). Normal install/setup still refuses — zero settings "
+                   "bytes written. Use './run.sh takeover-user-scope' to claim it explicitly, or "
+                   "'./run.sh remove-user-scope' for the aligned orphan cleanup.")
+
+    if state is not None:
+        # Operator-explicit takeover with a recorded owner: the ONE writer allowed to
+        # move the shared user-scope entry between roots. It moves the old owner's
+        # EXACT classified entry in place — takeover licenses moving THE registration,
+        # never collateral deletion, so an ambiguous store refuses here too.
+        old_root = state["packageRoot"]
+        if old_root == repo_dir:
+            _require_user_owner_entry(settings_path, old_root)
+            if preflight:
+                print("preflight: takeover ok (already this root; one unambiguous registration)")
+                return 0
+            _write_state(state_path, repo_dir, settings_path)
+            print(f"takeover: user-scope entwurf registration remains {repo_dir} (already this root)")
+            return 0
+        old_entry = _require_user_owner_entry(settings_path, old_root)
+        if preflight:
+            print(f"preflight: takeover would move {old_root} -> {repo_dir}")
+            return 0
+        _replace_packages_entry(settings_path, old_entry, repo_dir)
+        _write_state(state_path, repo_dir, settings_path)
+        print(f"takeover: user-scope entwurf registration moved {old_root} -> {repo_dir} (exact owner entry only)")
+        return 0
+
+    # ── no recorded owner (no state) ──
+    if not _has_entwurf_entries(settings_path, repo_dir):
+        if preflight:
+            print("preflight: takeover would claim {} (fresh; no other owner recorded)".format(repo_dir)
+                  if takeover else "preflight: install ok (fresh registration)")
+            return 0
+        # Fresh registration appends the exact entry directly — the broad register()
+        # collapse has nothing to normalize here and user scope never invokes it.
+        original_text = _read_text(settings_path)
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        data = _load(settings_path)
+        packages = _packages(settings_path, data)
+        data["packages"] = packages + [repo_dir]
+        _write(settings_path, data, original_text)
+        _write_state(state_path, repo_dir, settings_path)
+        if takeover:
+            print(f"takeover: user-scope entwurf registration now {repo_dir} (fresh; no other owner was recorded)")
+        else:
+            print(f"install: registered entwurf package -> {settings_path}")
+            print(f"install: package source -> {repo_dir} (owner state written)")
+        return 0
+    if _sole_exact_self_entry(settings_path, repo_dir):
+        # Legacy no-state entry that EXACTLY names this root: adopt by writing the
+        # owner state only — the settings bytes and mtime stay untouched.
+        if preflight:
+            print("preflight: install ok (legacy same-root adoption)")
+            return 0
+        _write_state(state_path, repo_dir, settings_path)
+        print(f"install: adopted legacy user-scope registration for {repo_dir} (owner state written; settings untouched)")
+        return 0
+    if takeover:
+        # Explicit claim of an ownerless legacy store: unambiguous only when a SINGLE
+        # entwurf-shaped entry exists — that entry IS the registration the operator
+        # asked to take over, and it is replaced in place. Two or more shapes cannot
+        # be attributed and refuse; collapsing them would be collateral deletion.
+        data = _load(settings_path) if settings_path.exists() else {}
+        packages = _packages(settings_path, data)
+        shaped = _entwurf_matches(packages, repo_dir, _settings_dir(settings_path))
+        if len(shaped) == 1:
+            old = source_of(shaped[0])
+            if preflight:
+                print(f"preflight: takeover would claim the legacy entry {old!r} -> {repo_dir}")
+                return 0
+            _replace_packages_entry(settings_path, shaped[0], repo_dir)
+            _write_state(state_path, repo_dir, settings_path)
+            print(f"takeover: claimed the legacy user-scope registration {old!r} -> {repo_dir} "
+                  "(single ownerless entry; no other root touched)")
+            return 0
+        _refuse(6, f"register-pi-package: takeover refused — {len(shaped)} legacy entwurf-shaped packages[] "
+                   "entries exist with NO recorded owner; the claim is ambiguous and collapsing them would "
+                   "delete entries this root cannot attribute. Zero settings bytes written — resolve the "
+                   "store by hand (see './run.sh doctor-pi-package'), then retry.")
+    _refuse(6, "register-pi-package: legacy user-scope entwurf entr(y/ies) exist with NO recorded owner and do not "
+               f"exactly name this root ({repo_dir}). Refusing to normalize them silently — zero settings bytes "
+               "written. Use './run.sh takeover-user-scope' to claim the registration explicitly.")
+    return 1  # unreachable
+
+
+def remove_user(settings_path: Path, repo_dir_arg: str, state_path: Path, orphan: bool,
+                preflight: bool = False) -> int:
+    repo_dir = str(Path(repo_dir_arg).resolve())
+    if settings_path.exists():
+        _refuse_symlink(settings_path)
+    state = _load_state(state_path)
+    if state is not None:
+        _check_settings_binding(state, settings_path, state_path)
+
+    if state is not None:
+        owner = state["packageRoot"]
+        if owner == repo_dir:
+            # Exact-entry inverse (#86 C2): the owned removal drops ONLY the recorded
+            # owner's classified exact entry. A missing/duplicated exact entry OR any
+            # additional entwurf-shaped root is ambiguity the classifier refuses,
+            # checked identically by preflight and writer.
+            _require_user_owner_entry(settings_path, owner)
+            if preflight:
+                print("preflight: remove ok (this root owns one unambiguous registration)")
+                return 0
+            _remove_exact_owner_entry(settings_path, owner)
+            state_path.unlink()
+            print(f"remove: removed the owner's exact packages[] entry from {settings_path} (owner state cleared)")
+            return 0
+        if os.path.isdir(owner):
+            _refuse(6, "register-pi-package: the user-scope registration is owned by another LIVE root: "
+                       f"{owner}. This root's inverse must not remove someone else's registration — zero settings "
+                       "bytes written. Run remove from that root, or take the entry over first.")
+        if orphan:
+            # run.sh's aligned orphan path: entry + package state + provider
+            # installerRoot all named this same MISSING root before the flag was
+            # passed. Same exact classifier as the owned inverse.
+            _require_user_owner_entry(settings_path, owner)
+            if preflight:
+                print(f"preflight: orphan cleanup would remove the MISSING owner {owner} (one unambiguous entry)")
+                return 0
+            _remove_exact_owner_entry(settings_path, owner)
+            state_path.unlink()
+            print(f"remove: orphan cleanup — removed the exact entry for the MISSING owner {owner} (state cleared)")
+            return 0
+        _refuse(6, "register-pi-package: the recorded owner root is MISSING: "
+                   f"{owner}. Refusing to remove without the aligned orphan path — run './run.sh remove-user-scope' "
+                   "so package entry, package state and provider installerRoot are checked together.")
+
+    # no state: same-owner-only under user scope — remove ONLY entries that exactly
+    # name this root; any other managed-looking shape is preserved and reported.
+    if not settings_path.exists():
+        print(f"remove: nothing to do ({settings_path} missing)")
+        return 0
+    if preflight:
+        print("preflight: remove ok (no owner state; self-exact entries only)")
+        return 0
+    original_text = _read_text(settings_path)
+    data = _load(settings_path)
+    packages = _packages(settings_path, data)
+    settings_dir = _settings_dir(settings_path)
+    matches = _entwurf_matches(packages, repo_dir, settings_dir)
+    self_removable = [
+        m for m in matches
+        if isinstance(m, str) and m == repo_dir
+    ]
+    preserved_rel = [m for m in matches if _is_relative_self_item(m, settings_dir, repo_dir)]
+    foreign_like = [m for m in matches if m not in self_removable and m not in preserved_rel]
+    if self_removable:
+        data["packages"] = [item for item in packages if item not in self_removable]
+        _write(settings_path, data, original_text)
+        print(f"remove: removed {len(self_removable)} entwurf packages[] entr{'y' if len(self_removable) == 1 else 'ies'} naming this root")
+    else:
+        print(f"remove: no entwurf packages[] entry naming this root ({settings_path})")
+    if preserved_rel:
+        print(f"remove: kept {len(preserved_rel)} settings-relative entwurf entr{'y' if len(preserved_rel) == 1 else 'ies'} — committed/operator source, not install state")
+    if foreign_like:
+        print(f"remove: kept {len(foreign_like)} entwurf-shaped entr{'y' if len(foreign_like) == 1 else 'ies'} with no recorded owner "
+              "(not provably this root's) — use './run.sh doctor-pi-package' / takeover-user-scope to resolve ownership")
+    return 0
+
+
+def doctor_user(settings_path: Path, repo_dir_arg: str, state_path: Path,
+                provider_state_path: Path | None = None) -> int:
+    """Package-side ownership verdict plus the package↔provider OWNERSHIP coupling
+    (installerRoot vs packageRoot). Provider RUNTIME verdicts stay with
+    doctor-pi-provider — this doctor never probes the bridge."""
+    repo_dir = str(Path(repo_dir_arg).resolve())
+    state = _load_state(state_path)
+    coupling_fail = False
+    if state is not None:
+        managed = state.get("managedSettingsPath")
+        if not isinstance(managed, str) or os.path.abspath(managed) != os.path.abspath(str(settings_path)):
+            print(f"doctor-pi-package: FAIL managedSettingsPath mismatch — the package state manages "
+                  f"{managed!r} but this host's target is {settings_path}")
+            coupling_fail = True
+    if provider_state_path is not None and provider_state_path.exists() and state is not None:
+        try:
+            pp = json.loads(provider_state_path.read_text())
+        except json.JSONDecodeError:
+            pp = None
+        if not isinstance(pp, dict):
+            print("doctor-pi-package: FAIL provider install-state is not readable as a JSON object — "
+                  "the ownership coupling cannot be judged from an unattributed state")
+            coupling_fail = True
+        else:
+            # One typed installerRoot verdict (#86 C2 corrective amendment, B blocker 3):
+            # the SAME classifier the provider writers refuse on, so a wrong-TYPE value
+            # can never read green here while install/remove fail closed on it.
+            installer_kind, installer_root = classify_installer_root(pp)
+            if installer_kind == "corrupt":
+                print("doctor-pi-package: FAIL provider installerRoot is CORRUPT — expected a non-empty string "
+                      "(owner) or null/absent (legacy); a wrong-typed value is unattributed and fail-closed")
+                coupling_fail = True
+            elif installer_kind == "owner" and installer_root != state["packageRoot"]:
+                print(f"doctor-pi-package: FAIL coupling mismatch — provider installerRoot {installer_root} "
+                      f"!= packageRoot {state['packageRoot']} (the two halves of the user-scope ownership disagree)")
+                coupling_fail = True
+            elif installer_kind == "legacy":
+                print("doctor-pi-package: note — provider install-state is LEGACY (no installerRoot); "
+                      "a same-root install/setup adopts it")
+        pp_managed = pp.get("managedSettingsPath") if isinstance(pp, dict) else None
+        if isinstance(pp_managed, str) and os.path.abspath(pp_managed) != os.path.abspath(str(settings_path)):
+            print(f"doctor-pi-package: FAIL provider managedSettingsPath mismatch — the provider state manages "
+                  f"{pp_managed!r} but this host's target is {settings_path}")
+            coupling_fail = True
+    data = _load(settings_path) if settings_path.exists() else {}
+    packages = _packages(settings_path, data)
+    settings_dir = _settings_dir(settings_path)
+    matches = _entwurf_matches(packages, repo_dir, settings_dir)
+
+    if state is None:
+        if not matches:
+            print("doctor-pi-package: unregistered — no owner state, no entwurf packages[] entry")
+            return 0
+        print(f"doctor-pi-package: legacy-no-state — {len(matches)} entwurf entr{'y' if len(matches) == 1 else 'ies'} with no recorded owner; "
+              "repair: './run.sh setup' from the owning root (exact-self adopts) or './run.sh takeover-user-scope'")
+        return 1
+    owner = state["packageRoot"]
+    owner_live = os.path.isdir(owner)
+    # The SAME exact-owner classifier the writers refuse on (#86 C2 corrective
+    # amendment, B blocker 2): a store the inverse would refuse — owner's exact
+    # entry missing/duplicated, or an extra entwurf-shaped root beside it — must
+    # read RED here, never "owned" through the broad shape matcher.
+    owner_exact, owner_extra = _classify_user_owner_entries(settings_path, owner)
+    if len(owner_exact) != 1 or owner_extra:
+        print(f"doctor-pi-package: mismatch — owner state records {owner} but the settings hold "
+              f"{len(owner_exact)} exact entr{'y' if len(owner_exact) == 1 else 'ies'} and "
+              f"{len(owner_extra)} additional entwurf-shaped entr{'y' if len(owner_extra) == 1 else 'ies'} "
+              "(expected exactly one exact entry and no other entwurf-shaped root)")
+        return 1
+    if not owner_live:
+        print(f"doctor-pi-package: missing-owner — recorded owner root {owner} does not exist; "
+              "repair: './run.sh takeover-user-scope' from a live root, or './run.sh remove-user-scope' (aligned orphan cleanup)")
+        return 1
+    if owner == repo_dir:
+        print(f"doctor-pi-package: owned — this root ({repo_dir}) owns the user-scope registration")
+        return 1 if coupling_fail else 0
+    print(f"doctor-pi-package: owned-by-other (live) — {owner} owns the user-scope registration; this root does not")
+    return 1 if coupling_fail else 0
+
+
 def main(argv: list[str]) -> int:
-    flags = {a for a in argv[1:] if a.startswith("--")}
-    args = [a for a in argv[1:] if not a.startswith("--")]
+    flag_names = {"--remove", "--dry-run", "--takeover", "--orphan-cleanup", "--doctor", "--preflight"}
+    args: list[str] = []
+    flags: set[str] = set()
+    scope = "project"
+    state_arg = ""
+    provider_state_arg = ""
+    i = 1
+    while i < len(argv):
+        a = argv[i]
+        if a == "--scope":
+            i += 1
+            scope = argv[i] if i < len(argv) else ""
+        elif a == "--state":
+            i += 1
+            state_arg = argv[i] if i < len(argv) else ""
+        elif a == "--provider-state":
+            i += 1
+            provider_state_arg = argv[i] if i < len(argv) else ""
+        elif a.startswith("--"):
+            flags.add(a)
+        else:
+            args.append(a)
+        i += 1
     do_remove = "--remove" in flags
     dry_run = "--dry-run" in flags
-    known = {"--remove", "--dry-run"}
-    unknown = flags - known
+    unknown = flags - flag_names
     if unknown:
         raise SystemExit(f"unknown flag(s): {', '.join(sorted(unknown))}")
+    if scope not in ("user", "project"):
+        raise SystemExit("register-pi-package.py: --scope must be user or project")
+    if scope == "user" and not state_arg:
+        raise SystemExit("register-pi-package.py: --state is required with --scope user")
+    for f in ("--takeover", "--orphan-cleanup", "--doctor", "--preflight"):
+        if f in flags and (scope != "user" or not state_arg):
+            raise SystemExit(f"register-pi-package.py: {f} requires --scope user --state <path>")
+    if "--orphan-cleanup" in flags and not do_remove:
+        raise SystemExit("register-pi-package.py: --orphan-cleanup is only supported with --remove")
+    if "--takeover" in flags and (do_remove or "--doctor" in flags):
+        raise SystemExit("register-pi-package.py: --takeover is an install action")
     # --dry-run is a REMOVE-only preview. Without --remove it would otherwise fall
     # through to the register path and WRITE — a flag literally named "dry-run"
     # mutating settings is an install-hygiene footgun, so reject it loud instead of
@@ -294,11 +799,24 @@ def main(argv: list[str]) -> int:
     if dry_run and not do_remove:
         raise SystemExit("--dry-run is only supported with --remove")
     if len(args) != 2:
-        raise SystemExit("usage: register-pi-package.py <settings.json> <repo_dir> [--remove] [--dry-run]")
+        raise SystemExit("usage: register-pi-package.py <settings.json> <repo_dir> [--remove] [--dry-run] "
+                         "[--scope user|project] [--state <path>] [--takeover] [--orphan-cleanup] [--doctor]")
     settings_path = Path(args[0])
     repo_dir_arg = args[1]
     resolved = str(Path(repo_dir_arg).resolve())
 
+    if scope == "user":
+        state_path = Path(state_arg)
+        preflight = "--preflight" in flags
+        if "--doctor" in flags:
+            return doctor_user(settings_path, repo_dir_arg, state_path,
+                               Path(provider_state_arg) if provider_state_arg else None)
+        if do_remove:
+            if dry_run:
+                raise SystemExit("register-pi-package.py: --dry-run is not supported with --scope user")
+            return remove_user(settings_path, repo_dir_arg, state_path, "--orphan-cleanup" in flags, preflight)
+        return register_user(settings_path, repo_dir_arg, state_path, "--takeover" in flags, preflight)
+
     if do_remove:
         n, kept = (would_remove if dry_run else remove)(settings_path, repo_dir_arg)
         verb = "would remove" if dry_run else "removed"