@junghanacs/entwurf 0.12.5 → 0.12.7

package/scripts/doctor-pi-provider.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// doctor-pi-provider — fail-loud doctor for the pi provider (entwurfProvider.mcpServers.
+// entwurf-bridge) ownership (#46 Task 2). Side-effect FREE (read-only). Uses the config.ts SSOT
+// `readProviderSettingsFile` so the effective (shadow-resolved) view matches what pi actually
+// loads — NOT a re-implemented merge (GPT D: a python re-impl drifts into "doctor green, runtime
+// red"). Reports user / project / EFFECTIVE command (project shadows user per-name, the
+// resolveProviderConfig rule), plus install-state ownership, and gates on stable-bin resolvability.
+//
+// Env overrides (for the hermetic smoke):
+//   PI_PROVIDER_GLOBAL_SETTINGS   default: $PI_CODING_AGENT_DIR/settings.json or ~/.pi/agent/settings.json
+//   PI_PROVIDER_PROJECT_SETTINGS  default: <cwd>/.pi/settings.json
+//   PI_PROVIDER_STATE             default: $XDG_DATA_HOME/entwurf/pi-provider/install-state.json
+//
+// Exit: 0 ok (incl. honest "never installed / unowned" notes) · 1 hard fail (malformed settings /
+// state-owned-but-drifted / stable bin dangling).
+import { execSync } from "node:child_process";
+import { existsSync, constants as FS, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readProviderSettingsFile } from "../pi-extensions/lib/acp/config.ts";
+
+const BARE = "entwurf-bridge";
+const KEY = "entwurf-bridge";
+
+const home = homedir();
+const agentDir = process.env.PI_CODING_AGENT_DIR || join(home, ".pi", "agent");
+const globalPath = process.env.PI_PROVIDER_GLOBAL_SETTINGS || join(agentDir, "settings.json");
+const projectPath = process.env.PI_PROVIDER_PROJECT_SETTINGS || join(process.cwd(), ".pi", "settings.json");
+const xdg = process.env.XDG_DATA_HOME || join(home, ".local", "share");
+const statePath = process.env.PI_PROVIDER_STATE || join(xdg, "entwurf", "pi-provider", "install-state.json");
+
+let hardFail = 0;
+const log = (s: string) => process.stdout.write(s + "\n");
+
+function commandOf(settings: { mcpServers?: Record<string, unknown> }): string | undefined {
+	const entry = settings.mcpServers?.[KEY];
+	if (entry && typeof entry === "object" && typeof (entry as { command?: unknown }).command === "string") {
+		return (entry as { command: string }).command;
+	}
+	return undefined;
+}
+
+// Does the command resolve in the environment (best local proxy for "where pi/agy runs")?
+// A bare name is looked up on PATH; a path must be an executable file.
+function resolvable(cmd: string): boolean {
+	if (cmd.includes("/")) {
+		try {
+			statSync(cmd);
+			// eslint-disable-next-line no-bitwise
+			return (statSync(cmd).mode & FS.S_IXUSR) !== 0;
+		} catch {
+			return false;
+		}
+	}
+	try {
+		// `command -v` is a POSIX sh builtin; use the default /bin/sh (NixOS has no /bin/bash).
+		execSync(`command -v ${cmd}`, { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+log("[pi-provider doctor]");
+
+// Read via the SSOT — a malformed settings file THROWS here (fail-loud, named file).
+let userCmd: string | undefined;
+let projCmd: string | undefined;
+try {
+	userCmd = commandOf(readProviderSettingsFile(globalPath).settings);
+	projCmd = commandOf(readProviderSettingsFile(projectPath).settings);
+} catch (err) {
+	log(`  FAIL: ${err instanceof Error ? err.message : String(err)}`);
+	process.exit(1);
+}
+
+// EFFECTIVE = project shadows user per-name (the resolveProviderConfig merge rule).
+const effectiveCmd = projCmd ?? userCmd;
+const effectiveScope = projCmd !== undefined ? "project" : userCmd !== undefined ? "user(global)" : "none";
+
+log("── scopes (project shadows user per-name)");
+log(`  user(global) ${globalPath}: ${userCmd ? `'${userCmd}'` : "entwurf-bridge NOT configured"}`);
+log(`  project      ${projectPath}: ${projCmd ? `'${projCmd}'` : "entwurf-bridge NOT configured"}`);
+log(`  EFFECTIVE (${effectiveScope}): ${effectiveCmd ? `'${effectiveCmd}'` : "none"}`);
+
+// install-state ownership (user scope). absent state on a configured effective is either a
+// pre-Task-2 install or a user-override we deliberately did not own.
+let ownership: string | undefined;
+if (existsSync(statePath)) {
+	try {
+		const st = JSON.parse(readFileSync(statePath, "utf8")) as { ownership?: string };
+		ownership = typeof st.ownership === "string" ? st.ownership : undefined;
+		log(`  state: install-state present (ownership=${ownership}).`);
+	} catch {
+		log(`  state: FAIL — install-state ${statePath} is unreadable/corrupt.`);
+		hardFail = 1;
+	}
+} else {
+	log("  state: no user-scope install-state.");
+}
+
+log("── verdict");
+if (effectiveCmd === undefined) {
+	log(
+		"  note: no entwurfProvider.mcpServers.entwurf-bridge in any scope (never installed — this is the '?'; run ./run.sh setup).",
+	);
+} else if (effectiveCmd === BARE) {
+	if (resolvable(effectiveCmd)) {
+		log(`  ok: effective command is the bare stable bin '${BARE}' and it RESOLVES.`);
+	} else {
+		log(`  FAIL: effective command is '${BARE}' but it does NOT resolve (run ./run.sh expose-dev-bin / npm bin-link).`);
+		hardFail = 1;
+	}
+} else {
+	// effective is NOT the bare bin. If state says we own it → drift (FAIL). Otherwise classify
+	// the effective command honestly: our OWN legacy repo start.sh (not yet adopted) is NOT a
+	// user override — say so distinctly so "run setup" is the clear next step. A truly foreign
+	// command is an unowned override left as the operator's choice. Neither is a hard fail.
+	const isLegacyManaged = effectiveCmd.endsWith("/entwurf/mcp/entwurf-bridge/start.sh");
+	if (ownership && ownership !== "user-override") {
+		log(
+			`  FAIL: state owns entwurf-bridge (ownership=${ownership}) but the effective command drifted to '${effectiveCmd}'.`,
+		);
+		hardFail = 1;
+	} else if (isLegacyManaged) {
+		log(
+			`  note: effective is our LEGACY managed repo path ('${effectiveCmd}'), not yet adopted to the bare stable bin. Run ./run.sh setup to normalize (this is the pre-Task-2 '?').`,
+		);
+	} else {
+		log(
+			`  note: entwurf-bridge is an UNOWNED override ('${effectiveCmd}') — effective is not the stable bin. Left as the operator's choice (run ./run.sh setup to adopt the bare bin).`,
+		);
+	}
+}
+
+if (hardFail) {
+	log("pi-provider doctor: FAIL.");
+	process.exit(1);
+}
+log("pi-provider doctor: ok.");

package/scripts/meta-bridge-doctor.sh

@@ -17,18 +17,22 @@ MKT_NAME="meta-bridge-local"
 PLUGIN="entwurf-meta-receive"
 CLAUDE_CFG="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
 REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-# LIB_EXT tracks the hook artifact mode (0.12.5): installed packages ship the
+# The live artifact lives under the XDG data dir (dev clone and installed package
+# alike — never the checkout). Prefer the path RECORDED in install-state so a doctor
+# run under a different XDG_DATA_HOME than install still hashes the REAL assembled
+# bundle (and state.py check compares the same recorded marketplace path); fall back
+# to the current-XDG computation only when no state exists yet (fresh host).
+# LIB_EXT still tracks the hook artifact mode (0.12.5): installed packages ship the
 # tsc-emitted `.js` closure (node_modules-safe), dev clones run the `.ts` source.
 # The writer-version parity below hashes meta-session.<LIB_EXT> so an installed
 # `.js` bundle is compared against the SAME-pipeline dist `.js`, never against the
 # `.ts` source (which would hash-mismatch and false-STALE).
+ASM="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/meta-bridge/.assembled"
+RECORDED_ASM="$(python3 "$REPO/scripts/meta-bridge-state.py" assembled-path --repo "$REPO" 2>/dev/null || true)"
+[ -n "$RECORDED_ASM" ] && ASM="$RECORDED_ASM"
 case "$REPO" in
-  */node_modules/@junghanacs/entwurf)
-    ASM="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/meta-bridge/.assembled"
-    LIB_EXT="js" ;;
-  *)
-    ASM="$REPO/pi/meta-bridge/.assembled"
-    LIB_EXT="ts" ;;
+  */node_modules/@junghanacs/entwurf) LIB_EXT="js" ;;
+  *)                                  LIB_EXT="ts" ;;
 esac
 # shellcheck source=scripts/meta-bridge-hook-log.sh
 source "$REPO/scripts/meta-bridge-hook-log.sh"
@@ -89,9 +93,43 @@ else
 fi
 
 echo "[plugin install (global / --scope user)]"
-if claude plugin list 2>/dev/null | grep -q "$PLUGIN@$MKT_NAME"; then
+PLUGIN_LIST_JSON="$(claude plugin list --json 2>/dev/null || true)"
+PLUGIN_FACT="$(printf '%s' "$PLUGIN_LIST_JSON" | python3 -c '
+import json, sys
+try:
+    rows = json.load(sys.stdin)
+except Exception:
+    raise SystemExit(1)
+target = sys.argv[1]
+row = next((x for x in rows if isinstance(x, dict) and x.get("id") == target), None)
+if row is None:
+    print("absent")
+else:
+    print("present")
+    print("true" if row.get("enabled") is True else "false")
+    errors = row.get("errors")
+    print("; ".join(str(x) for x in errors) if isinstance(errors, list) else "")
+' "$PLUGIN@$MKT_NAME" 2>/dev/null || true)"
+if [ -n "$PLUGIN_FACT" ]; then
+  PLUGIN_PRESENT="$(printf '%s\n' "$PLUGIN_FACT" | sed -n '1p')"
+  PLUGIN_ENABLED="$(printf '%s\n' "$PLUGIN_FACT" | sed -n '2p')"
+  PLUGIN_ERRORS="$(printf '%s\n' "$PLUGIN_FACT" | sed -n '3p')"
+  if [ "$PLUGIN_PRESENT" = "absent" ]; then
+    bad "$PLUGIN@$MKT_NAME not installed — run ./run.sh install-meta-bridge"
+  else
+    ok "$PLUGIN@$MKT_NAME present"
+    if [ -n "$PLUGIN_ERRORS" ]; then
+      bad "enabled=$PLUGIN_ENABLED but FAILED TO LOAD: $PLUGIN_ERRORS — the SessionStart hook is not running; re-run ./run.sh install-meta-bridge"
+    elif [ "$PLUGIN_ENABLED" = "true" ]; then
+      ok "enabled and loadable"
+    else
+      bad "installed but NOT enabled"
+    fi
+  fi
+# Compatibility fallback for a Claude floor whose plugin list has no --json surface.
+elif claude plugin list 2>/dev/null | grep -q "$PLUGIN@$MKT_NAME"; then
   ok "$PLUGIN@$MKT_NAME present"
-  claude plugin list 2>/dev/null | grep -A3 "$PLUGIN@$MKT_NAME" | grep -qi "enabled" && ok "enabled" || bad "installed but NOT enabled"
+  claude plugin list 2>/dev/null | grep -A3 "$PLUGIN@$MKT_NAME" | grep -qi "enabled" && ok "enabled (text fallback; load errors unavailable)" || bad "installed but NOT enabled"
 else
   bad "$PLUGIN@$MKT_NAME not installed — run ./run.sh install-meta-bridge"
 fi

package/scripts/meta-bridge-install.sh

@@ -4,7 +4,8 @@
 # needs, so a user never hand-edits hook/plugin settings or passes --plugin-dir.
 #
 # Mechanism (all proven on 2026-06-05):
-#   1. ASSEMBLE a self-contained plugin under pi/meta-bridge/.assembled/ (gitignored):
+#   1. ASSEMBLE a self-contained plugin under the version-stable XDG data dir
+#      ($XDG_DATA_HOME/entwurf/meta-bridge/.assembled) — NEVER inside the checkout:
 #      copy the committed skeleton, copy the entry shell + its lib (so
 #      ${CLAUDE_PLUGIN_ROOT} self-locates them), and BAKE the node abspath into
 #      hooks.json. The node path is the ONLY templated surface — the mailbox /
@@ -13,9 +14,10 @@
 #      entwurf_inbox_read tool comes from USER-scope entwurf-bridge MCP wiring
 #      (`claude mcp add -s user ...`). Project-scoped .mcp.json is deliberately
 #      not enough: a /tmp native session would wake without a receipt tool.
-#   2. marketplace add <stable .assembled>  (dev: repo-local; installed package:
-#      version-stable XDG data dir; NOT /tmp — ephemeral source would break
-#      `claude plugin marketplace update`).
+#   2. marketplace add <stable XDG .assembled>  (both dev clone and installed
+#      package assemble into the same version-stable XDG data dir; NOT /tmp —
+#      ephemeral source would break `claude plugin marketplace update`, and NOT
+#      the checkout — repo housekeeping must never cut the live user-scope wiring).
 #   3. install entwurf-meta-receive@meta-bridge-local --scope user  (= global:
 #      every native session auto-loads it; no manual --plugin-dir).
 #   4. install/update USER-scope entwurf-bridge MCP, so every native session has
@@ -31,26 +33,27 @@ REPO="$(cd "$HERE/.." && pwd)"
 MKT_NAME="meta-bridge-local"
 PLUGIN="entwurf-meta-receive"
 SRC="$REPO/pi/meta-bridge"
-# Dev clone: keep the marketplace source inside the checkout for transparent
-# inspection. Installed package: assemble into a version-stable operator path;
-# Claude settings store this directory path and package-manager upgrades do not
-# rewrite it, so a pnpm-store path would go stale on version/peer churn.
-#
-# The SAME installed-vs-dev split also picks the hook artifact (0.12.5): an
-# installed marketplace source lives below node_modules, where Node REFUSES
-# `--experimental-strip-types` on `.ts` (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING),
-# so installed packages run the tsc-emitted `meta-bridge-hook.js` closure (mirrors
-# start.sh/store-doctor). Dev clones live outside node_modules and run the `.ts`
-# source directly for transparent editing. HOOK_ENTRY is baked into hooks.json.
+# The live marketplace artifact ALWAYS assembles under the version-stable XDG data
+# dir — dev clone and installed package alike. Claude settings store this directory
+# path and package-manager upgrades do not rewrite it (a pnpm-store path would go
+# stale on version/peer churn). Critically it lives OUTSIDE the checkout, so repo
+# housekeeping (git clean -xfd, check/smoke) can never cut the global user-scope
+# wiring: dev vs installed is a difference of SOURCE ORIGIN (repo tree vs npm
+# package we assemble FROM), never of where the live artifact lands.
+ASM="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/meta-bridge/.assembled"
+# The hook ARTIFACT form still splits by install shape (0.12.5): an installed
+# package lives below node_modules, where Node REFUSES `--experimental-strip-types`
+# on `.ts` (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so it runs the tsc-emitted
+# `meta-bridge-hook.js` closure (mirrors start.sh/store-doctor). A dev clone lives
+# outside node_modules — and so does the XDG artifact — so it runs the `.ts` source
+# directly. HOOK_ENTRY is baked into hooks.json.
 case "$REPO" in
   */node_modules/@junghanacs/entwurf)
-    ASM="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/meta-bridge/.assembled"
     HOOK_ENTRY="meta-bridge-hook.js"
     HOOK_SRC="$REPO/mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-hook.js"
     LIB_SRC="$REPO/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js"
     LIB_EXT="js" ;;
   *)
-    ASM="$SRC/.assembled"
     HOOK_ENTRY="meta-bridge-hook.ts"
     HOOK_SRC="$REPO/pi-extensions/meta-bridge-hook.ts"
     LIB_SRC="$REPO/pi-extensions/lib/meta-session.ts"

package/scripts/meta-bridge-state.py

@@ -513,9 +513,33 @@ def check(repo: Path, asm: Path) -> None:
         failures.append(f"{claude_root_config_path()} root is not an object")
         root = {}
 
+    # The marketplace source path in settings was written by apply() from the
+    # RECORDED assembledMarketplacePath. Compare against that recorded value, not the
+    # --asm passed here: a doctor/check run under a different XDG_DATA_HOME than
+    # install must not false-FAIL a correctly-wired marketplace. Fall back to --asm
+    # only if the recorded field is somehow absent.
+    recorded_asm = state.get("assembledMarketplacePath")
+    # Shape-validate the recorded path (basename included). Every state our code
+    # writes carries this field (init_state/prepare/apply), so a missing/empty/
+    # non-string value is itself corruption — NOT a reason to fall back to --asm and
+    # PASS. And a malformed value that matches a same-malformed settings entry (both
+    # hand-corrupted) would otherwise slip the comparison below and greenlight a
+    # bogus marketplace source. This mirrors the uninstall.sh honest-inverse guard:
+    # only the exact install suffix …/entwurf/meta-bridge/.assembled is valid.
+    ASM_SUFFIX = "/entwurf/meta-bridge/.assembled"
+    if not isinstance(recorded_asm, str) or not recorded_asm.endswith(ASM_SUFFIX):
+        failures.append(
+            f"install-state assembledMarketplacePath is missing/malformed ('{recorded_asm}'); "
+            f"must end in {ASM_SUFFIX} — repair state or re-run install-meta-bridge"
+        )
+    marketplace_expected = (
+        {"source": {"source": "directory", "path": recorded_asm}}
+        if recorded_asm
+        else desired_marketplace(asm)
+    )
     checks = [
         (["enabledPlugins", PLUGIN_REF], True, "enabled plugin"),
-        (["extraKnownMarketplaces", MARKETPLACE], desired_marketplace(asm), "known marketplace"),
+        (["extraKnownMarketplaces", MARKETPLACE], marketplace_expected, "known marketplace"),
         (["statusLine"], desired_statusline(repo), "statusLine"),
     ] + [(path_, desired, name) for name, path_, desired in MANAGED_SETTINGS_SCALARS]
     for path_, expected, label in checks:
@@ -554,6 +578,7 @@ def main() -> int:
             "apply",
             "preflight-uninstall",
             "uninstall",
+            "assembled-path",
             "check",
             "managed-keys",
             "desired-mcp",
@@ -564,7 +589,13 @@ def main() -> int:
     parser.add_argument("--asm", default=None, type=Path)
     args = parser.parse_args()
     repo = args.repo.resolve()
-    asm = (args.asm or (repo / "pi" / "meta-bridge" / ".assembled")).resolve()
+    # The live artifact always lives under the XDG data dir — dev clone and
+    # installed package alike (mirror meta-bridge-install.sh's ASM resolution).
+    # install/doctor pass --asm explicitly; this default is the same XDG path so a
+    # bare invocation never falls back to a repo-internal marketplace source.
+    xdg_data = Path(os.environ.get("XDG_DATA_HOME") or (Path.home() / ".local" / "share"))
+    default_asm = xdg_data / "entwurf" / "meta-bridge" / ".assembled"
+    asm = (args.asm or default_asm).resolve()
     try:
         if args.command == "prepare":
             prepare(repo, asm)
@@ -574,6 +605,13 @@ def main() -> int:
             preflight_uninstall()
         elif args.command == "uninstall":
             uninstall()
+        elif args.command == "assembled-path":
+            # Print the RECORDED assembled marketplace path so the honest inverse
+            # (uninstall) removes exactly what install created — not a path
+            # recomputed from a possibly-changed XDG_DATA_HOME. Requires state.
+            state = load_state(required=True)
+            assert state is not None  # load_state(required=True) dies otherwise
+            print(state.get("assembledMarketplacePath", ""))
         elif args.command == "check":
             check(repo, asm)
         elif args.command == "managed-keys":

package/scripts/meta-bridge-uninstall.sh

@@ -26,6 +26,23 @@ command -v python3 >/dev/null || die "'python3' not on PATH. It is required for
 # delete live plugin/MCP entries before failing — guessing by side effect.
 python3 "$REPO/scripts/meta-bridge-state.py" preflight-uninstall --repo "$REPO"
 
+# Read + shape-validate the RECORDED assembled path BEFORE any side effect. The
+# honest inverse must remove exactly what install created; recomputing from
+# ${XDG_DATA_HOME} would orphan the real artifact if it changed since install. If
+# the recorded path is missing/corrupt we CANNOT safely remove the artifact, so we
+# fail loud HERE — before touching any Claude registration or the state file (no
+# guessing, no partial uninstall, no side-effect-then-WARN).
+ASM_RECORDED="$(python3 "$REPO/scripts/meta-bridge-state.py" assembled-path --repo "$REPO")"
+# Validate the FULL recorded path — basename included, not just the parent dir. The
+# rm below targets MB_DIR (the parent meta-bridge dir), so a parent-only check would
+# let a corrupt basename (…/entwurf/meta-bridge/not-assembled) pass as "well-formed"
+# and still nuke the real .assembled + Claude registrations. Only the exact install
+# suffix …/entwurf/meta-bridge/.assembled is a safe honest-inverse target.
+case "$ASM_RECORDED" in
+  */entwurf/meta-bridge/.assembled) MB_DIR="$(dirname "$ASM_RECORDED")" ;;   # …/entwurf/meta-bridge
+  *) die "install-state assembledMarketplacePath is missing/corrupt ('$ASM_RECORDED'); refusing to uninstall so the live artifact is not orphaned. Repair the state file or re-run install-meta-bridge, then uninstall." ;;
+esac
+
 if command -v claude >/dev/null; then
   claude plugin uninstall "$PLUGIN@$MKT_NAME" >/dev/null 2>&1 || true
   claude plugin marketplace remove "$MKT_NAME" >/dev/null 2>&1 || true
@@ -37,16 +54,10 @@ fi
 
 python3 "$REPO/scripts/meta-bridge-state.py" uninstall --repo "$REPO"
 
-# Remove the assembled marketplace source too — an honest inverse must not orphan
-# it. Installed packages assemble into a version-stable operator data dir
-# (~/.local/share/entwurf/meta-bridge/.assembled); leaving that tree behind is the
-# only meta-bridge footprint uninstall would otherwise leak. Dev clones drop their
-# gitignored in-checkout .assembled. Mirror install-meta-bridge's ASM resolution.
-case "$REPO" in
-  */node_modules/@junghanacs/entwurf)
-    rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/meta-bridge"
-    rmdir "${XDG_DATA_HOME:-$HOME/.local/share}/entwurf" 2>/dev/null || true ;;
-  *)
-    rm -rf "$REPO/pi/meta-bridge/.assembled" ;;
-esac
+# Remove the assembled marketplace source (validated above): the parent meta-bridge
+# dir of the RECORDED .assembled, then the now-empty entwurf dir. This rm can NEVER
+# reach inside the checkout, so repo housekeeping and this uninstall are structurally
+# disjoint (the 0.12.x statusline-`?` impurity class is extinct, not guarded).
+rm -rf "$MB_DIR"
+rmdir "$(dirname "$MB_DIR")" 2>/dev/null || true   # …/entwurf if empty
 echo "[meta-bridge-uninstall] DONE"

package/scripts/register-pi-package.py

@@ -0,0 +1,183 @@
+#!/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:
+  - 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
+(entwurf-notes, openclaw-entwurf) is neither wrongly registered-over nor wrongly
+removed. Every non-entwurf package and every other settings key is preserved.
+
+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
+implementation — mirrors the meta-bridge-state.py split.
+
+Usage: register-pi-package.py <settings.json> <repo_dir> [--remove]
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+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:
+    """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
+    entwurf-notes, openclaw-entwurf, or somebody else's git repo named entwurf.
+
+    Managed shapes:
+      - the exact resolved repo dir;
+      - an npm install path ending in node_modules/@junghanacs/entwurf;
+      - an explicit npm package source for @junghanacs/entwurf;
+      - 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".
+    """
+    p = source.rstrip("/")
+    if p == repo_dir or p.endswith("/node_modules/@junghanacs/entwurf"):
+        return True
+    if p == "npm:@junghanacs/entwurf" or p.startswith("npm:@junghanacs/entwurf@"):
+        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())
+        if not isinstance(data, dict):
+            raise SystemExit(f"{settings_path} is not a JSON object")
+        return data
+    return {}
+
+
+def _packages(settings_path: Path, data: dict) -> list:
+    packages = data.get("packages")
+    if packages is None:
+        return []
+    if not isinstance(packages, list):
+        # A settings file with a corrupt packages shape must NOT be silently
+        # coerced to [] — that would drop the operator's real packages.
+        raise SystemExit(f"{settings_path}: packages is not a JSON array")
+    return packages
+
+
+def _entwurf_matches(packages: list, repo_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]
+    ]
+
+
+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)
+    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:
+        return "noop"
+
+    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")
+    return "registered"
+
+
+def remove(settings_path: Path, repo_dir_arg: str) -> int:
+    """Drop every entwurf entry (any shape/path). Returns the count removed."""
+    repo_dir = str(Path(repo_dir_arg).resolve())
+    if not settings_path.exists():
+        return 0
+    data = _load(settings_path)
+    packages = _packages(settings_path, data)
+
+    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)
+
+
+def would_remove(settings_path: Path, repo_dir_arg: str) -> int:
+    """Count the entwurf entries a --remove WOULD drop, 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.
+    """
+    repo_dir = str(Path(repo_dir_arg).resolve())
+    if not settings_path.exists():
+        return 0
+    data = _load(settings_path)
+    packages = _packages(settings_path, data)
+    return len(_entwurf_matches(packages, repo_dir))
+
+
+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("--")]
+    do_remove = "--remove" in flags
+    dry_run = "--dry-run" in flags
+    known = {"--remove", "--dry-run"}
+    unknown = flags - known
+    if unknown:
+        raise SystemExit(f"unknown flag(s): {', '.join(sorted(unknown))}")
+    # --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
+    # silently registering.
+    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]")
+    settings_path = Path(args[0])
+    repo_dir_arg = args[1]
+    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)
+        if n:
+            print(f"remove: removed {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
+
+    result = register(settings_path, repo_dir_arg)
+    if result == "noop":
+        print(f"install: entwurf package already registered (no-op) -> {resolved}")
+    else:
+        print(f"install: registered entwurf package -> {settings_path}")
+        print(f"install: package source -> {resolved}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))