@junghanacs/entwurf 0.12.8 → 0.12.10

package/scripts/pi_settings_io.py

@@ -0,0 +1,65 @@
+"""pi_settings_io — the shared serializer for the pi settings.json files this repo WRITES.
+
+Both Python writers touch the SAME file (`<repo>/.pi/settings.json` at project scope,
+`~/.pi/agent/settings.json` at user scope):
+
+  - register-pi-package.py   → packages[]
+  - register-pi-provider.py  → entwurfProvider.mcpServers.entwurf-bridge
+
+A settings file can be tracked and owned by a formatter (this repo's own is: tab
+indented, biome-governed, pinned byte-for-byte by check-install-surface S7b–S7d), so a
+writer that re-serializes it in its own house style turns `install` into a source edit.
+#53 B closed that for the packages writer and left the provider writer open — the same
+file, the same defect, one function call away. The rules therefore live HERE rather than
+in either script, because a rule that has to be remembered at each call site is exactly
+what shipped the bug twice:
+
+  1. NO WRITE WHEN NOTHING CHANGES. The strongest idempotence is an untouched file —
+     same bytes, same mtime. Compare the mutated document to the one that was loaded and
+     skip the write when they are equal; only the caller knows what "changed" means, so
+     each one asks `unchanged` and decides.
+  2. A GENUINE REWRITE KEEPS THE FILE'S OWN INDENT UNIT. Narrower than it sounds: this
+     preserves the indent UNIT, not a formatter's line-collapsing decisions, so a rewrite
+     is NOT guaranteed to come back formatter-clean. Byte identity comes from rule 1.
+
+Ships inside `scripts/` (package.json `files` carries the directory whole, with
+`__pycache__`/`*.pyc` excluded), and both importers add their own directory to sys.path
+so the import holds however they are invoked.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+# The first indented line's leading whitespace is the file's unit. `\S` so a blank or
+# whitespace-only line never answers for the document.
+_INDENT = re.compile(r"\n([ \t]+)\S")
+
+
+def detect_indent(text: str | None) -> str | int:
+    """The file's own indent unit — a tab, or N spaces. Defaults to 2 for a new/one-line
+    file, which is what both writers produced before they knew to ask."""
+    if not text:
+        return 2
+    m = _INDENT.search(text)
+    if not m:
+        return 2
+    unit = m.group(1)
+    return "\t" if unit[0] == "\t" else len(unit)
+
+
+def dumps(data: dict, indent: str | int) -> str:
+    """Serialize with the given unit and exactly one trailing newline."""
+    return json.dumps(data, indent=indent) + "\n"
+
+
+def unchanged(before: dict, after: dict) -> bool:
+    """Would writing `after` change what the file MEANS?
+
+    Value equality, not byte equality, and deliberately so: dict `==` ignores key ORDER,
+    so a document whose keys merely moved is reported unchanged and the operator's own
+    ordering survives. The caller must pass a `before` taken BEFORE any mutation — both
+    writers mutate in place, so they parse the raw text twice rather than aliasing it.
+    """
+    return before == after

package/scripts/register-pi-package.py

@@ -1,18 +1,51 @@
 #!/usr/bin/env python3
 """Register (or --remove) entwurf in a pi settings.json packages[].
 
-The SINGLE predicate / idempotency / fail-loud SSOT shared by BOTH scopes and by
-remove, so install and uninstall can never drift to different meanings:
+One MATCHING predicate (is_entwurf_source) + one idempotency / fail-loud SSOT,
+shared by BOTH scopes and by remove, so "which entries are ours" cannot drift
+between install and uninstall:
   - project  <repo>/.pi/settings.json     (run.sh install_local_package / remove_local_package)
   - user     ~/.pi/agent/settings.json    (run.sh register_user_scope_citizen)
 
 Register is idempotent: absent → append REPO_DIR; already the sole canonical
 entry → no-op (file not rewritten, mtime stable); any other entwurf entry (object
-form, stale path, duplicate) collapses into one canonical string form. Remove
-drops every entwurf entry. Both use is_entwurf_source(), so a look-alike repo
+form, stale path, duplicate) collapses into one canonical string form.
+
+Matching is shared; the ACTION on a match is not, and the asymmetry is deliberate.
+Remove drops every MANAGED shape the matcher recognizes — the resolved repo dir, an
+`…/node_modules/@junghanacs/entwurf` install path, an `npm:@junghanacs/entwurf[@ver]`
+spec, a stale local path whose last segment is `entwurf` — including shapes register
+itself never literally wrote, because those are how an operator's earlier install or
+a moved clone left this package registered. It preserves exactly ONE class: a
+settings-RELATIVE entry that resolves to repo_dir (see below). A look-alike repo
 (entwurf-notes, openclaw-entwurf) is neither wrongly registered-over nor wrongly
 removed. Every non-entwurf package and every other settings key is preserved.
 
+CANONICAL IS NOT ONLY THE ABSOLUTE PATH. A packages[] entry is resolved by pi
+against the SETTINGS FILE'S OWN DIRECTORY, so this repo's committed
+`.pi/settings.json` names itself portably as `".."` — the exact form
+check-install-surface S7c pins. Comparing entries against the resolved absolute
+path ALONE did not recognize that as entwurf, so `setup` appended the absolute
+path beside it and rewrote the tracked, biome-governed file in a foreign style:
+a dev clone went RED at `pnpm check` step 1, diagnosed as a "formatting" error
+(#53 B). Two rules follow, and they are the same rule read forwards and backwards:
+  - register: an entry that RESOLVES to repo_dir is already canonical → no-op, and
+    when a rewrite is genuinely needed a settings-relative self-reference is kept
+    as the survivor, so the portable form is never silently absolutized;
+  - remove: register only ever WRITES the absolute form, so a settings-relative
+    self-reference cannot be install's own output — it was authored by the repo
+    (this one commits `".."`) or by the operator. Uninstall is install's inverse,
+    not a settings editor: it leaves that ONE class in place and SAYS SO on stdout,
+    rather than deleting source bytes install never wrote. The cost is stated
+    rather than hidden: on a settings file whose only entwurf entry is relative,
+    `--remove` is a no-op and the package stays registered until a human edits it.
+    would_remove() asks the same split, so `--dry-run` can never disagree with what
+    `--remove` does.
+A rewrite also preserves the file's existing indentation instead of forcing 2
+spaces. That is narrower than it sounds — it keeps the indent UNIT, not a
+formatter's line-collapsing decisions — so the byte-identity guarantee this repo's
+own settings depend on comes from the no-op path, never from the writer's style.
+
 This wiring (user scope) dropped when `pi install` was removed from setup
 (2026-07-03: `--entwurf-control` unknown in a foreign cwd). Extracting it here
 lets run.sh (both scopes + remove) and smoke-user-scope-citizen share ONE
@@ -24,16 +57,53 @@ Usage: register-pi-package.py <settings.json> <repo_dir> [--remove]
 from __future__ import annotations
 
 import json
+import os
+import re
 import sys
 from pathlib import Path
 
+# The serializer rules are SHARED with register-pi-provider.py — both write the same
+# settings file, and a copied indent-detector is how the second writer stayed open after
+# the first one was closed (#53 B). sys.path[0] already holds this directory when the
+# 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
+
+# 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.
+_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+
 
 def source_of(item: object) -> object:
     """The package spec of a packages[] entry — string form or {"source": …}."""
     return item.get("source") if isinstance(item, dict) else item
 
 
-def is_entwurf_source(source: str, repo_dir: str) -> bool:
+def is_settings_relative_self(source: str, settings_dir: str, repo_dir: str) -> bool:
+    """True iff this entry is a SETTINGS-RELATIVE path naming repo_dir itself.
+
+    This is the repo's own committed portable form (`".."` in
+    <repo>/.pi/settings.json) — functionally identical to the absolute entry,
+    because pi resolves a relative package source against the settings file's own
+    directory. It is also the one shape register never writes, which is what lets
+    remove treat it as source rather than as install state.
+
+    Anything carrying a scheme (npm:/git:/https:) is a spec, not a path; anything
+    absolute (`/`, `~`) is not settings-relative. Everything else is resolved and
+    compared — a relative entry only matches when it genuinely names this repo, so
+    `../../repos/gh/andenken` stays untouched.
+    """
+    p = source.rstrip("/")
+    if not p or _SCHEME.match(p) or p.startswith(("/", "~")):
+        return False
+    try:
+        return str((Path(settings_dir) / p).resolve()) == repo_dir
+    except OSError:
+        return False
+
+
+def is_entwurf_source(source: str, repo_dir: str, settings_dir: str | None = None) -> bool:
     """True iff this package entry points at THIS entwurf — the only entries
     register/remove may touch. Strict on purpose: user-scope settings are GLOBAL,
     so a substring "entwurf" match would wrongly eat unrelated repos like
@@ -43,6 +113,8 @@ def is_entwurf_source(source: str, repo_dir: str) -> bool:
       - the exact resolved repo dir;
       - an npm install path ending in node_modules/@junghanacs/entwurf;
       - an explicit npm package source for @junghanacs/entwurf;
+      - a settings-relative path that RESOLVES to the repo dir (the committed
+        portable `".."`), when the caller supplies settings_dir;
       - a local filesystem path whose final directory is literally "entwurf"
         (dev clone / stale move). Remote URL/git-like strings are NOT treated as
         local paths merely because their last segment is "entwurf".
@@ -52,10 +124,14 @@ def is_entwurf_source(source: str, repo_dir: str) -> bool:
         return True
     if p == "npm:@junghanacs/entwurf" or p.startswith("npm:@junghanacs/entwurf@"):
         return True
+    if settings_dir is not None and is_settings_relative_self(p, settings_dir, repo_dir):
+        return True
     local_like = p.startswith(("/", "./", "../", "~"))
     return local_like and Path(p).name == "entwurf"
 
 
+
+
 def _load(settings_path: Path) -> dict:
     if settings_path.exists():
         data = json.loads(settings_path.read_text())
@@ -76,62 +152,130 @@ def _packages(settings_path: Path, data: dict) -> list:
     return packages
 
 
-def _entwurf_matches(packages: list, repo_dir: str) -> list:
+def _settings_dir(settings_path: Path) -> str:
+    """The directory a relative packages[] entry is resolved against — the settings
+    file's own parent, the way pi reads it. Never the process cwd: run.sh and the
+    gates invoke this from anywhere."""
+    return str(settings_path.parent.resolve()) if settings_path.parent.exists() else str(settings_path.parent)
+
+
+def _is_relative_self_item(item: object, settings_dir: str, repo_dir: str) -> bool:
+    """is_settings_relative_self, asked of a packages[] ENTRY of either shape."""
+    src = source_of(item)
+    return isinstance(src, str) and is_settings_relative_self(src, settings_dir, repo_dir)
+
+
+def _entwurf_matches(packages: list, repo_dir: str, settings_dir: str) -> list:
     return [
         item for item in packages
-        if isinstance(source_of(item), str) and is_entwurf_source(source_of(item), repo_dir)  # type: ignore[arg-type]
+        if isinstance(source_of(item), str) and is_entwurf_source(source_of(item), repo_dir, settings_dir)  # type: ignore[arg-type]
     ]
 
 
+def _write(settings_path: Path, data: dict, original_text: str | None) -> None:
+    """Serialize with the file's own indentation (pi_settings_io.detect_indent)."""
+    settings_path.write_text(dumps(data, detect_indent(original_text)))
+
+
+def _read_text(settings_path: Path) -> str | None:
+    return settings_path.read_text() if settings_path.exists() else None
+
+
 def register(settings_path: Path, repo_dir_arg: str) -> str:
     """"noop" if entwurf is already the sole canonical entry (file untouched),
     else "registered" (rewritten with a single canonical entry)."""
     repo_dir = str(Path(repo_dir_arg).resolve())
     settings_path.parent.mkdir(parents=True, exist_ok=True)
+    original_text = _read_text(settings_path)
     data = _load(settings_path)
     packages = _packages(settings_path, data)
-
-    entwurf_entries = _entwurf_matches(packages, repo_dir)
-    # Already correct iff exactly ONE entwurf entry and it is the canonical string
-    # form at repo_dir. Order-insensitive; no rewrite → mtime stable.
-    if len(entwurf_entries) == 1 and entwurf_entries[0] == repo_dir:
+    settings_dir = _settings_dir(settings_path)
+
+    entwurf_entries = _entwurf_matches(packages, repo_dir, settings_dir)
+    # Already correct iff exactly ONE entwurf entry and it NAMES repo_dir — either as
+    # the canonical absolute string or as a settings-relative path resolving there.
+    # Both are the same registration to pi, so both are a no-op: order-insensitive, no
+    # rewrite, mtime stable. Recognizing only the absolute form is what made `setup`
+    # duplicate this repo's own committed `".."` and restyle the tracked file (#53 B).
+    # Both arms require the STRING form, so an object-form entry still collapses to a
+    # canonical string exactly as before.
+    if len(entwurf_entries) == 1 and isinstance(entwurf_entries[0], str) and (
+        entwurf_entries[0] == repo_dir
+        or is_settings_relative_self(entwurf_entries[0], settings_dir, repo_dir)
+    ):
         return "noop"
 
+    # A rewrite keeps the PORTABLE form when the file already had one: absolutizing a
+    # committed `".."` would repair the duplicate and dirty the tracked bytes in the
+    # same breath. Otherwise the canonical absolute path is what install writes.
+    survivor = next(
+        (
+            source_of(e) for e in entwurf_entries
+            if _is_relative_self_item(e, settings_dir, repo_dir)
+        ),
+        repo_dir,
+    )
     filtered = [item for item in packages if item not in entwurf_entries]
-    data["packages"] = filtered + [repo_dir]
-    settings_path.write_text(json.dumps(data, indent=2) + "\n")
+    data["packages"] = filtered + [survivor]
+    _write(settings_path, data, original_text)
     return "registered"
 
 
-def remove(settings_path: Path, repo_dir_arg: str) -> int:
-    """Drop every entwurf entry (any shape/path). Returns the count removed."""
+def _removable(packages: list, repo_dir: str, settings_dir: str) -> tuple[list, list]:
+    """Split entwurf entries into (removable, preserved).
+
+    REMOVABLE = every managed shape the matcher recognizes, including ones register
+    never literally wrote (an npm spec, a node_modules path, a stale clone path) —
+    those are how a previous install or a moved checkout left this package
+    registered, and the inverse has to reach them.
+
+    PRESERVED = settings-relative self-references, the one shape register CANNOT
+    have produced (it always writes the resolved absolute path). Such an entry is
+    the repo's committed portable registration or the operator's own hand edit.
+    Deleting it would make uninstall a source editor, which is the defect #53 B is
+    about, pointed the other way. main() prints what was kept so the incompleteness
+    is loud rather than silent.
+    """
+    matches = _entwurf_matches(packages, repo_dir, settings_dir)
+    preserved = [item for item in matches if _is_relative_self_item(item, settings_dir, repo_dir)]
+    removable = [item for item in matches if item not in preserved]
+    return removable, preserved
+
+
+def remove(settings_path: Path, repo_dir_arg: str) -> tuple[int, int]:
+    """Drop every MANAGED entwurf entry (any shape/path), preserving settings-relative
+    self-references. Returns (removed, preserved)."""
     repo_dir = str(Path(repo_dir_arg).resolve())
     if not settings_path.exists():
-        return 0
+        return 0, 0
+    original_text = _read_text(settings_path)
     data = _load(settings_path)
     packages = _packages(settings_path, data)
+    settings_dir = _settings_dir(settings_path)
 
-    entwurf_entries = _entwurf_matches(packages, repo_dir)
-    if not entwurf_entries:
-        return 0
-    data["packages"] = [item for item in packages if item not in entwurf_entries]
-    settings_path.write_text(json.dumps(data, indent=2) + "\n")
-    return len(entwurf_entries)
+    removable, preserved = _removable(packages, repo_dir, settings_dir)
+    if not removable:
+        return 0, len(preserved)
+    data["packages"] = [item for item in packages if item not in removable]
+    _write(settings_path, data, original_text)
+    return len(removable), len(preserved)
 
 
-def would_remove(settings_path: Path, repo_dir_arg: str) -> int:
-    """Count the entwurf entries a --remove WOULD drop, writing NOTHING.
+def would_remove(settings_path: Path, repo_dir_arg: str) -> tuple[int, int]:
+    """Count what a --remove WOULD drop and what it would preserve, writing NOTHING.
 
     Read-only companion to remove() for --dry-run — lets a caller (e.g. run.sh's
     project `remove` pointer note) decide whether the global user-scope inverse is
-    worth suggesting without mutating the operator's settings.
+    worth suggesting without mutating the operator's settings. It asks the SAME
+    predicate remove asks, so a dry-run can never over- or under-report it.
     """
     repo_dir = str(Path(repo_dir_arg).resolve())
     if not settings_path.exists():
-        return 0
+        return 0, 0
     data = _load(settings_path)
     packages = _packages(settings_path, data)
-    return len(_entwurf_matches(packages, repo_dir))
+    removable, preserved = _removable(packages, repo_dir, _settings_dir(settings_path))
+    return len(removable), len(preserved)
 
 
 def main(argv: list[str]) -> int:
@@ -156,18 +300,20 @@ def main(argv: list[str]) -> int:
     resolved = str(Path(repo_dir_arg).resolve())
 
     if do_remove:
-        if dry_run:
-            n = would_remove(settings_path, repo_dir_arg)
-            if n:
-                print(f"remove: would remove {n} entwurf packages[] entr{'y' if n == 1 else 'ies'} from {settings_path}")
-            else:
-                print(f"remove: no entwurf packages[] entry to remove ({settings_path})")
-            return 0
-        n = remove(settings_path, repo_dir_arg)
+        n, kept = (would_remove if dry_run else remove)(settings_path, repo_dir_arg)
+        verb = "would remove" if dry_run else "removed"
         if n:
-            print(f"remove: removed {n} entwurf packages[] entr{'y' if n == 1 else 'ies'} from {settings_path}")
+            print(f"remove: {verb} {n} entwurf packages[] entr{'y' if n == 1 else 'ies'} from {settings_path}")
         else:
             print(f"remove: no entwurf packages[] entry to remove ({settings_path})")
+        # Never silent: an inverse that deliberately leaves something behind has to
+        # say what and why, or the operator reads "removed" as "fully unregistered".
+        if kept:
+            print(
+                f"remove: kept {kept} settings-relative entwurf entr{'y' if kept == 1 else 'ies'} "
+                f"({settings_path}) — install never writes that form, so it is committed/operator "
+                "source, not install state; edit the file by hand to drop it"
+            )
         return 0
 
     result = register(settings_path, repo_dir_arg)

package/scripts/register-pi-provider.py

@@ -39,6 +39,16 @@ import json
 import os
 import sys
 
+# Shared with register-pi-package.py: both writers touch the SAME settings file, so the
+# "no write when nothing changes / keep the file's indent unit" rules live in one module
+# instead of being remembered at each call site. Closing only the packages writer for
+# #53 B left THIS one restyling the repo's own tracked, biome-governed settings on every
+# `install` — semantically a no-op, byte-wise a RED `pnpm check`. sys.path[0] already
+# holds this directory when the script is run by path (how run.sh and the gates 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, unchanged  # noqa: E402
+
 SERVER_KEY = "entwurf-bridge"
 BARE_COMMAND = "entwurf-bridge"
 STATE_SCHEMA_VERSION = 1
@@ -78,9 +88,14 @@ def _atomic_write(path: str, text: str) -> None:
     os.replace(tmp, path)
 
 
-def _load(path: str) -> dict:
+def _read(path: str) -> str:
+    if not os.path.exists(path):
+        return ""
     with open(path, "r", encoding="utf-8") as fh:
-        raw = fh.read()
+        return fh.read()
+
+
+def _parse_settings(path: str, raw: str) -> dict:
     if raw.strip() == "":
         return {}
     try:
@@ -92,10 +107,33 @@ def _load(path: str) -> dict:
     return data
 
 
+def _load(path: str) -> dict:
+    return _parse_settings(path, _read(path))
+
+
 def _dump(data: dict) -> str:
+    """For files THIS script owns end to end (the install-state record), where no
+    formatter has a claim. A settings file goes through _persist instead."""
     return json.dumps(data, indent=2) + "\n"
 
 
+def _persist(path: str, before: dict, after: dict, original_text: str) -> bool:
+    """Write a SETTINGS file — but only if `after` actually differs from what was
+    loaded, and then in the file's own indent unit. Returns True when it wrote.
+
+    This is the whole of #53 B on this writer. `install` is documented as idempotent
+    and a managed-current classification changes nothing, yet the old unconditional
+    `_atomic_write` re-serialized the document every time: this repo's committed
+    `.pi/settings.json` is tab-indented with compact arrays, came back at indent=2, and
+    took `pnpm check` RED at its first step — reported as a formatting error, which is
+    what sent the diagnosis away from "install wrote this" (#53 B, both rounds).
+    """
+    if unchanged(before, after):
+        return False
+    _atomic_write(path, dumps(after, detect_indent(original_text)))
+    return True
+
+
 def _now() -> str:
     import datetime
 
@@ -140,7 +178,11 @@ def cmd_install(settings_path: str, repo_dir: str, scope: str, state_path: str)
         _die(3, f"register-pi-provider: refusing to adopt {settings_path} — it is a symlink to {target} "
                 f"(someone else's SSOT). Manage it there, or replace it with a regular file, then retry.")
 
-    data = _load(settings_path) if os.path.exists(settings_path) else {}
+    raw = _read(settings_path)
+    # Parsed TWICE on purpose: everything below mutates in place, so `before` has to be
+    # an independent document or the comparison would be against itself.
+    before = _parse_settings(settings_path, raw)
+    data = _parse_settings(settings_path, raw)
     provider, servers = _provider_servers(data, create=True)
     _prune_legacy(servers, repo_dir)   # independent of entwurf-bridge ownership
     existing = servers.get(SERVER_KEY)
@@ -149,11 +191,12 @@ def cmd_install(settings_path: str, repo_dir: str, scope: str, state_path: str)
 
     if ownership == "user-override":
         # DO NOT overwrite our key, DO NOT own it (no state). doctor reports it as unowned. Still
-        # persist so any legacy prune above (and a materialized parent) is written.
+        # persist IF the legacy prune above (or a materialized parent) actually changed something.
         sys.stdout.write(
             f"install: preserved entwurfProvider.mcpServers.{SERVER_KEY} (user override, NOT owned: {existing_cmd!r})\n"
         )
-        _atomic_write(settings_path, _dump(data))
+        if not _persist(settings_path, before, data, raw):
+            sys.stdout.write(f"install: no change — {settings_path} left untouched (bytes and mtime stable)\n")
         return
 
     # absent / managed-current / managed-legacy → normalize to the bare stable bin.
@@ -164,10 +207,15 @@ def cmd_install(settings_path: str, repo_dir: str, scope: str, state_path: str)
     else:
         newval["args"] = []
     servers[SERVER_KEY] = newval
-    _atomic_write(settings_path, _dump(data))
+    wrote = _persist(settings_path, before, data, raw)
     sys.stdout.write(
         f"install: {ownership} → entwurfProvider.mcpServers.{SERVER_KEY} = {BARE_COMMAND} (bare stable bin)\n"
     )
+    # The desired value AND the legacy prune both already held: nothing to say to the
+    # file. Reported so an operator (and the gate) can tell "already correct" from
+    # "rewritten to the same thing" — only the first leaves a tracked file alone.
+    if not wrote:
+        sys.stdout.write(f"install: no change — {settings_path} left untouched (bytes and mtime stable)\n")
 
     if scope == "user":
         if state_path:
@@ -201,7 +249,9 @@ def cmd_remove(settings_path: str, repo_dir: str, scope: str, state_path: str) -
         if os.path.islink(managed):
             _die(3, f"register-pi-provider: refusing to uninstall — {managed} became a symlink since install.")
         if os.path.exists(managed):
-            data = _load(managed)
+            raw = _read(managed)
+            before = _parse_settings(managed, raw)
+            data = _parse_settings(managed, raw)
             provider, servers = _provider_servers(data, create=False)
             # honest inverse: absent/managed-* → remove OUR key (a legacy repo path is NOT
             # restored — it was our old managed value, not a user value).
@@ -211,7 +261,9 @@ def cmd_remove(settings_path: str, repo_dir: str, scope: str, state_path: str) -
                     provider.pop("mcpServers", None)
             if isinstance(provider, dict) and not provider:
                 data.pop("entwurfProvider", None)
-            _atomic_write(managed, _dump(data))
+            # Same rule as install: an inverse that has nothing left to undo must not
+            # restyle the file on its way out.
+            _persist(managed, before, data, raw)
         os.remove(state_path)
         sys.stdout.write(f"remove: removed our {SERVER_KEY} key (ownership={state.get('ownership')}) from {managed}\n")
         return
@@ -222,7 +274,9 @@ def cmd_remove(settings_path: str, repo_dir: str, scope: str, state_path: str) -
         return
     if os.path.islink(settings_path):
         _die(3, f"register-pi-provider: refusing to touch {settings_path} — it is a symlink.")
-    data = _load(settings_path)
+    raw = _read(settings_path)
+    before = _parse_settings(settings_path, raw)
+    data = _parse_settings(settings_path, raw)
     provider, servers = _provider_servers(data, create=False)
     if not isinstance(servers, dict):
         sys.stdout.write("remove: no entwurfProvider.mcpServers — nothing to do.\n")
@@ -242,7 +296,11 @@ def cmd_remove(settings_path: str, repo_dir: str, scope: str, state_path: str) -
         sys.stdout.write(f"remove: preserved entwurfProvider.mcpServers.{SERVER_KEY} (user override: {existing_cmd!r})\n")
     else:  # absent
         sys.stdout.write(f"remove: entwurfProvider.mcpServers.{SERVER_KEY} already absent.\n")
-    _atomic_write(settings_path, _dump(data))
+    # `absent` + nothing pruned is the common case on a clean checkout, and it used to
+    # rewrite the file anyway — a project `remove` restyled the tracked settings exactly
+    # as install did.
+    if not _persist(settings_path, before, data, raw):
+        sys.stdout.write(f"remove: no change — {settings_path} left untouched (bytes and mtime stable)\n")
 
 
 def _parse(argv: list):

package/scripts/smoke-acp-raw-turn-live.ts

@@ -3,7 +3,7 @@
 //   LIVE=1 ./run.sh smoke-acp-raw-turn-live
 //
 // What this proves (and ONLY this): the pinned Claude ACP adapter
-// (@agentclientprotocol/claude-agent-acp@0.61.0) spawns, speaks the ACP wire
+// (@agentclientprotocol/claude-agent-acp@0.62.0) spawns, speaks the ACP wire
 // protocol over stdio NDJSON, and returns one real model turn. It is the
 // bytes-flow proof that the S2a dep surface is not just installable but
 // actually drivable — before any provider/overlay/streamSimple code (S2b+).

package/scripts/smoke-acp-socket-citizen-live.ts

@@ -20,7 +20,7 @@
 // LIVE-only (spawns a real pi + opens a real socket) — kept OUT of `pnpm check`;
 // honest skip when LIVE!=1 (skip = CI safety, NOT an acceptance PASS).
 //   LIVE=1 ./run.sh smoke-acp-socket-citizen-live
-//   override model via ENTWURF_S1_MODEL (default claude-opus-4-8).
+//   override model via ENTWURF_S1_MODEL (default claude-opus-5).
 
 import { type ChildProcess, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
@@ -34,7 +34,7 @@ import { terminateChild } from "./lib/acp-child-cleanup.ts";
 import { waitForPiRecord } from "./lib/pi-record-discovery.ts";
 
 const ACP_PROVIDER = "entwurf";
-const ACP_MODEL = process.env.ENTWURF_S1_MODEL?.trim() || "claude-opus-4-8";
+const ACP_MODEL = process.env.ENTWURF_S1_MODEL?.trim() || "claude-opus-5";
 
 const REAL_CONTROL_DIR = path.join(os.homedir(), ".pi", "entwurf-control");
 const SOCKET_SUFFIX = ".sock";

package/scripts/smoke-acp-v2-send-live.ts

@@ -32,26 +32,41 @@
 // The isolated world also keeps the operator's live store and mailbox clean: a
 // smoke that delivers into the real garden would page a human.
 //
-// KNOWN OPEN DEFECT this gate catches — bundled-MCP readiness (2026-07-24). Two
-// independent failures were first read as the model declining an explicit
-// instruction, and the transcripts said otherwise: in both, the entwurf tool was
-// ABSENT from the session's schema. The two models then behaved differently, which
-// is why the shared cause was easy to miss — in this gate's failure (a standalone
-// run) the model called anyway and the runtime answered `No such tool available:
-// mcp__entwurf-bridge__entwurf_v2`; in the sibling smoke-acp-bundled-mcp-live's
-// failure (a separate run, half an hour later, inside a release-gate aggregate) the
-// model read its schema first, reported that only Read/Bash/Edit/Write/Skill were
-// exposed, and refused to invent a result for a tool it did not have. Two
-// independent runs, different behaviour, one defect: the server was not there to be
-// called. The window is
-// structural: claude-agent-acp 0.61.0's createSession awaits only
+// KNOWN OPEN DEFECT this gate catches — bundled-MCP readiness (2026-07-24).
+// SSOT for the ledger and the claim tiers: ROADMAP 「번들 MCP readiness race」 +
+// docs/acp-backend-rail.md §11. Keep this comment at the strength those carry.
+//
+// OBSERVED (established): in three runs the entwurf tool was ABSENT from the
+// session's schema — the same SYMPTOM each time, reached by two different model
+// behaviours, which is why one shared symptom was easy to miss. In this gate's
+// failure (a standalone run) the model called anyway and the runtime answered
+// `No such tool available: mcp__entwurf-bridge__entwurf_v2`; in the sibling
+// smoke-acp-bundled-mcp-live's failure (a separate run, half an hour later,
+// inside a release-gate aggregate) the model read its schema first, reported that
+// only Read/Bash/Edit/Write/Skill were exposed, and refused to invent a result for
+// a tool it did not have.
+//
+// ESTABLISHED CONTRACT GAP (not the same as a cause): there is no client-side
+// readiness fence on this path. claude-agent-acp's createSession awaits only
 // `initializationResult()`, and this backend prompts right after
 // (acp/backend.ts:718-790) — nothing waits for the configured MCP servers to reach
-// `connected`, though claude-agent-sdk 0.3.217 exposes exactly that via
-// `mcpServerStatus()`. Both observed hits came under heavy concurrent load, which
-// is correlation, not established cause. So this gate stays MUST: its failures are
-// OURS. Until the readiness wait exists, a FAIL here is a real release blocker and
-// must not be re-read as model flakiness.
+// `connected`, though claude-agent-sdk exposes exactly that via
+// `mcpServerStatus()`.
+//
+// OPEN (do NOT write as settled): whether that missing fence is what produced the
+// three observations. No controlled repro exists yet, and the load association is
+// correlation only. Do not restate this as "one defect" or "the cause".
+//
+// Bump note: measured at claude-agent-acp 0.61.0 / claude-agent-sdk 0.3.217;
+// re-checked at the 2026-07-27 bump to 0.62.0 / 0.3.219 — the adapter's `dist/` is
+// byte-identical across 0.61.0→0.62.0 and adds no readiness fence. That is an
+// unchanged ABSENCE of any explicit wait, not an unchanged window: the transitive
+// SDK moved and MCP startup lives inside it, so effective timing may differ.
+//
+// So this gate stays MUST: it TELLS the model which tool to call, so a failure
+// here is OURS, not model preference. While the symptom and the contract gap
+// remain unresolved, a FAIL here is a real release blocker and must not be
+// re-read as model flakiness.
 //
 // LIVE-only — kept OUT of `pnpm check`; honest skip when LIVE!=1 (skip = CI safety,
 // NOT an acceptance PASS). Model override: ENTWURF_ACP_PROVIDER_MODEL (default sonnet).