platformforge 0.2.1__tar.gz → 0.2.3__tar.gz

{platformforge-0.2.1 → platformforge-0.2.3}/CHANGELOG.md

@@ -1,6 +1,27 @@
 # CHANGELOG
 
 All notable changes. Format: wave/feature, the "why", key commits.
+## [0.2.3] - 2026-10-24
+
+### Security
+
+- Vendored `_installkit` 1.0.4: unsafe ledger keys surfaced in
+  `status().drift.unsafe`; `doctor` marks them non-repairable.
+
+## [0.2.2] - 2026-10-29
+
+### Fixed
+
+- `_forgecontext` v1.3.3 + `_installkit` v1.0.3 (vendored): `repair_context`
+  reports malformed capability files per-file instead of crashing;
+  context/install locks carry a unique ownership token; poisoned journals
+  quarantine instead of wedging later ops; asset/ledger paths are
+  validated before disk writes (`FORGE-INSTALL-UNSAFE-PATH`);
+  `_atomic_write` preserves file modes.
+- A `BLOCKED` check on the mandatory context-registry component now marks
+  the receipt `failed` (nonzero exit) — on install AND on both uninstall
+  paths.
+
 ## [0.2.1] - 2026-10-22
 
 ### Fixed

{platformforge-0.2.1 → platformforge-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: platformforge
-Version: 0.2.1
+Version: 0.2.3
 Summary: Agentic Platform Engineering intelligence platform — deterministic, offline-first, evidence-first
 Project-URL: Homepage, https://github.com/EdgarSocrates98/platform-forge
 Project-URL: Repository, https://github.com/EdgarSocrates98/platform-forge

{platformforge-0.2.1 → platformforge-0.2.3}/docs/audits/FORGE_CONTEXT_FINAL_HOMOLOGATION.md

@@ -305,3 +305,16 @@ grep -c 'def test_' tests/test_{install_lifecycle,wheel_isolation,
 | Wheel smoke (venv limpo) | PASS | `pip install platformforge==0.2.0` + `platformforge --version` → `0.2.0` |
 
 Notas: installkit canônico 1.0.2 (`_SOURCE_SHA256 a15ca78bb34a0109`), bootstrap 1.1.1 — propagados aos 7 carriers; `vendor.py --check` CLEAN ×7. `data-sentinel-forge`: **deferido pelo dono** (outro CLI evoluindo).
+
+## Pós-release hotfix — evidência de publicação patch (2026-10-23 UTC)
+
+Patch motivado pelo review: `UnicodeDecodeError` não-tipado em docs de
+consumidor não-UTF-8 quebrava install **e** uninstall.
+
+| Item | Estado | Evidência |
+|---|---|---|
+| Tag | CRIADA | `v0.2.1` |
+| GitHub Release | CRIADO | `gh release view v0.2.1` |
+| PyPI | PUBLICADO | `pypi.org/pypi/platformforge/json` → `0.2.1` |
+| Wheel smoke | PASS | wheel publicado contém `_forgecontext` v1.3.2 (`_read_doc` presente) — verificado via `pip download platformforge==0.2.1` |
+| Regressão | PASS | teste cp1252 `AGENTS.md` → `FORGE-CONTEXT-CONFLICT` nomeado em install e uninstall |

{platformforge-0.2.1 → platformforge-0.2.3}/docs/economy-parity/VALIDATION-RECEIPT.json

@@ -11,42 +11,42 @@
     "economy-agentic": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_agents_waste.py tests/test_economy_evals.py -k uniqueness or debate or duplication or fanout or waste or stagnant",
-      "seconds": 3.09
+      "seconds": 3.13
     },
     "economy-budget": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_contracts.py -k budget or limit or protected or dimension",
-      "seconds": 2.61
+      "seconds": 2.37
     },
     "economy-cache": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_cache.py",
-      "seconds": 2.72
+      "seconds": 2.98
     },
     "economy-closure": {
       "ok": true,
       "reproduce": "python -c import sys\nfrom pathlib import Path\nreq = {'docs/economy-parity/FINAL-REPORT.md':\n         ['validated_sha', 'remote_ci', 'known gap'],\n       'docs/economy-parity/FINAL-MATRIX.md':\n         ['validated', 'externally-unverified'],\n       'docs/economy-parity/ECONOMY-BENCHMARKS.md':\n         ['Control Plane Overhead', 'End-to-End'],\n       'docs/economy/ROUTING.md':\n         ['decide', 'advisory'],\n       'docs/economy-parity/POLISH-BASELINE.md': ['drift']}\nbad = []\nfor f, needles in req.items():\n    p = Path(f)\n    if not p.is_file(): bad.append(('missing', f)); continue\n    txt = p.read_text()\n    for n in needles:\n        if n not in txt: bad.append((f, n))\nm = Path('docs/economy-parity/FINAL-MATRIX.md').read_text()\nif '\\n' + '|' in m and ' fully-production' in m:\n    bad.append(('matrix', 'overclaimed status'))\nif bad: print(bad); sys.exit(1)\nprint('closure docs coherent')\n && pytest -q tests/test_economy_closure.py",
-      "seconds": 3.56
+      "seconds": 3.53
     },
     "economy-context": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_gateway.py -k TestGateway or TestLazy or TestRole or Suff",
-      "seconds": 2.63
+      "seconds": 2.75
     },
     "economy-contracts": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_contracts.py tests/test_economy_v2.py",
-      "seconds": 4.0
+      "seconds": 3.87
     },
     "economy-evals": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_evals.py",
-      "seconds": 3.22
+      "seconds": 3.15
     },
     "economy-qpt": {
       "ok": true,
       "reproduce": "pytest -q tests/test_qpt_v2.py tests/test_economy_fleet_qpt.py",
-      "seconds": 8.55
+      "seconds": 8.31
     },
     "economy-receipt": {
       "ok": true,
@@ -56,30 +56,30 @@
     "economy-reconcile": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_gateway.py tests/test_economy_evals.py -k reconcil or mismatch or unobserved",
-      "seconds": 3.1
+      "seconds": 2.96
     },
     "economy-resume": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_gateway.py -k resume or checkpoint",
-      "seconds": 2.68
+      "seconds": 2.41
     },
     "economy-routing": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_evals.py -k routing or profile or champion or simple_task",
-      "seconds": 3.07
+      "seconds": 2.93
     },
     "economy-surface": {
       "ok": true,
       "reproduce": "python -c import subprocess, sys\ncmds = [\n ['platformforge','economy','doctor'],\n ['platformforge','economy','checkpoint','--run-id','gate',\n  '--spent','{\"tokens\":1}'],\n ['platformforge','economy','resume','--run-id','gate'],\n ['platformforge','economy','reconcile',\n  '--planned','{\"tokens\":1}','--observed','{\"tokens\":2}'],\n ['platformforge','economy','explain','--run-id','gate'],\n ['platformforge','cache','stats'],\n ['platformforge','cache','gc'],\n ['platformforge','context','capsule','--task','t',\n  '--facts','[{\"fact_id\":\"f\"}]'],\n ['platformforge','context','gc'],\n ['platformforge','routing','explain','--signal','{}'],\n ['platformforge','routing','compare',\n  '--champion','{}','--challenger','{}'],\n]\nfor c in cmds:\n    r = subprocess.run(c, capture_output=True)\n    if r.returncode not in (0, 2):\n        print('FAIL', c, r.returncode, r.stderr[-300:])\n        sys.exit(1)\nprint('all economy verbs respond')\n",
-      "seconds": 15.63
+      "seconds": 15.88
     },
     "economy-verification": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_pricing_verify.py",
-      "seconds": 2.64
+      "seconds": 2.69
     }
   },
-  "generated_at": "2026-10-23T00:41:26Z",
+  "generated_at": "2026-10-23T07:24:59Z",
   "kind": "platformforge/economy-validation-receipt/1",
   "known_gaps": [
     "real provider pricing catalog not bundled (declared-rates engine only, by design)",
@@ -93,7 +93,7 @@
   "remote_ci": "not independently verified",
   "schema": "platformforge/economy-validation-receipt/v1",
   "spec": "prompt_evo_economy.md",
-  "validated_sha": "f245fbab25869f66b7e13c7d4f844864a1697041",
+  "validated_sha": "1c7cfe24a06242f2a45ad770fc1240abf160eebf",
   "validator": "scripts/validate.py",
   "validator_version": "economy-validation-receipt/v1",
   "verdict": "validated"

{platformforge-0.2.1 → platformforge-0.2.3}/platformforge/__init__.py

@@ -4,4 +4,4 @@ Deterministic-first, offline-first, evidence-first. The core never imports
 LLM SDKs, cloud SDKs, or MCP — those live behind optional adapters.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"

{platformforge-0.2.1 → platformforge-0.2.3}/platformforge/_forgecontext.py

@@ -100,6 +100,7 @@ import json
 import os
 import re
 import shutil
+import stat
 import sys
 import tempfile
 import time
@@ -107,10 +108,10 @@ from collections.abc import Iterable, Mapping
 from pathlib import Path, PurePosixPath
 from typing import Any
 
-_FORGECONTEXT_VERSION = "1.3.2"
+_FORGECONTEXT_VERSION = "1.3.3"
 # Filled by the vendor step (scripts/installkit/vendor.py) — the sha256 of
 # the canonical source body, so drift checks can compare vendored copies.
-_SOURCE_SHA256 = "2aab49d08c331431"
+_SOURCE_SHA256 = "18ebe75c6281a3f5"
 
 SCHEMA_MANIFEST = "forge/context/v1"
 SCHEMA_REGISTRY = "forge/context-registry/v1"
@@ -241,12 +242,17 @@ def _load_json(path: Path, default: Any = None) -> Any:
 
 def _atomic_write(path: Path, data: bytes) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
+    # mkstemp lands 0600 — preserve an existing file's mode so a managed
+    # merge never downgrades the user's permissions.
+    mode = stat.S_IMODE(path.stat().st_mode) if path.is_file() else None
     fd, tmp = tempfile.mkstemp(prefix=path.name, dir=str(path.parent))
     try:
         with os.fdopen(fd, "wb") as fh:
             fh.write(data)
             fh.flush()
             os.fsync(fh.fileno())
+        if mode is not None:
+            os.chmod(tmp, mode)
         os.replace(tmp, path)
     finally:
         if os.path.exists(tmp):
@@ -269,15 +275,18 @@ def _pid_alive(pid: int) -> bool | None:
 
 
 class _Lock:
-    """O_EXCL lockfile carrying ``{pid, created_at}``. Stale locks — dead
-    holder or older than ``stale_after_s`` — are reclaimed once so an
-    interrupted op never bricks the registry."""
+    """O_EXCL lockfile carrying ``{pid, created_at, token}``. Stale locks —
+    dead holder or older than ``stale_after_s`` — are reclaimed once so an
+    interrupted op never bricks the registry. The token guards release:
+    a file reclaimed or rewritten by another claimant is never unlinked
+    by ``__exit__``."""
 
     def __init__(self, lock: Path, stale_after_s: float = 900.0) -> None:
         self._lock = lock
         self._stale = stale_after_s
         self.held = False
         self.recovered = False
+        self._token: str | None = None
 
     def __enter__(self) -> _Lock:
         try:
@@ -294,12 +303,30 @@ class _Lock:
                     E_LOCKED, f"context lock at {self._lock} could not be reclaimed"
                 ) from exc
             self.recovered = True
-            self._create()
+            try:
+                self._create()
+            except FileExistsError:
+                raise LockError(
+                    E_LOCKED,
+                    f"context lock at {self._lock} lost to a concurrent reclaimer",
+                ) from None
             return self
 
     def _create(self) -> None:
+        self._token = hashlib.sha256(
+            f"{os.getpid()}:{time.time_ns()}:{self._lock}".encode()
+        ).hexdigest()[:24]
         fd = os.open(str(self._lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
-        os.write(fd, _json_bytes({"pid": os.getpid(), "created_at": _utc_now()}))
+        os.write(
+            fd,
+            _json_bytes(
+                {
+                    "pid": os.getpid(),
+                    "created_at": _utc_now(),
+                    "token": self._token,
+                }
+            ),
+        )
         os.close(fd)
         self.held = True
 
@@ -331,9 +358,16 @@ class _Lock:
         return age > self._stale
 
     def __exit__(self, *exc: object) -> None:
-        if self.held:
-            with contextlib.suppress(OSError):
-                self._lock.unlink()
+        try:
+            if self.held:
+                # Only release a lock that still carries OUR token — a
+                # reclaimed/stolen file belongs to its current claimant.
+                doc = _load_json(self._lock)
+                if isinstance(doc, dict) and doc.get("token") == self._token:
+                    with contextlib.suppress(OSError):
+                        self._lock.unlink()
+        finally:
+            self.held = False
 
 
 def acquire_lock(ctx_dir: Path) -> _Lock:
@@ -1417,7 +1451,23 @@ def _qualified_ids(manifest: Mapping[str, Any]) -> list[str]:
 def _entry_from_manifest(
     manifest: dict[str, Any], cap_sha: str, prev: dict[str, Any] | None, now: str
 ) -> dict[str, Any]:
-    inst = manifest["installed"]
+    fid = str(manifest.get("forge_id") or "?")
+    inst = manifest.get("installed")
+    if not isinstance(inst, Mapping):
+        raise ContextError(
+            E_SCHEMA,
+            f"{_capability_rel(fid)}: missing required 'installed' — "
+            "repair or remove the capability file",
+        )
+    missing = [
+        k for k in ("forge_id", "name", "version", "state", "recorded_by") if k not in manifest
+    ]
+    if missing:
+        raise ContextError(
+            E_SCHEMA,
+            f"{_capability_rel(fid)}: missing required keys {missing} — "
+            "repair or remove the capability file",
+        )
     return {
         "forge_id": manifest["forge_id"],
         "owner": manifest["forge_id"],
@@ -1535,31 +1585,44 @@ def _recover_journal(ctx: Path, root: Path) -> dict[str, Any] | None:
     recovered: dict[str, Any] | None = None
     now = _utc_now()
     if isinstance(journal, dict):
-        op = journal.get("op")
-        if op == "register" and isinstance(journal.get("manifest"), dict):
-            if not validate_manifest(journal["manifest"]):
-                _apply_register(ctx, root, journal["manifest"], now)
-                recovered = {"op": "register", "forge_id": journal["manifest"]["forge_id"]}
-        elif op == "unregister" and isinstance(journal.get("forge_id"), str):
-            _apply_unregister(ctx, root, journal["forge_id"], now)
-            recovered = {"op": "unregister", "forge_id": journal["forge_id"]}
-        elif op == "install" and isinstance(journal.get("manifest"), dict):
-            if not validate_manifest(journal["manifest"]):
-                _apply_register(ctx, root, journal["manifest"], now)
-                if journal.get("docs", True):
-                    _docs_install_apply(
-                        root, journal["manifest"], tuple(journal.get("legacy_tags") or ())
-                    )
-                recovered = {
-                    "op": "install",
-                    "forge_id": journal["manifest"]["forge_id"],
-                }
-        elif op == "uninstall" and isinstance(journal.get("forge_id"), str):
-            _apply_unregister(ctx, root, journal["forge_id"], now)
-            _docs_uninstall_apply(
-                root, journal["forge_id"], tuple(journal.get("legacy_tags") or ())
-            )
-            recovered = {"op": "uninstall", "forge_id": journal["forge_id"]}
+        try:
+            op = journal.get("op")
+            if op == "register" and isinstance(journal.get("manifest"), dict):
+                if not validate_manifest(journal["manifest"]):
+                    _apply_register(ctx, root, journal["manifest"], now)
+                    recovered = {"op": "register", "forge_id": journal["manifest"]["forge_id"]}
+            elif op == "unregister" and isinstance(journal.get("forge_id"), str):
+                _apply_unregister(ctx, root, journal["forge_id"], now)
+                recovered = {"op": "unregister", "forge_id": journal["forge_id"]}
+            elif op == "install" and isinstance(journal.get("manifest"), dict):
+                if not validate_manifest(journal["manifest"]):
+                    _apply_register(ctx, root, journal["manifest"], now)
+                    if journal.get("docs", True):
+                        _docs_install_apply(
+                            root, journal["manifest"], tuple(journal.get("legacy_tags") or ())
+                        )
+                    recovered = {
+                        "op": "install",
+                        "forge_id": journal["manifest"]["forge_id"],
+                    }
+            elif op == "uninstall" and isinstance(journal.get("forge_id"), str):
+                _apply_unregister(ctx, root, journal["forge_id"], now)
+                _docs_uninstall_apply(
+                    root, journal["forge_id"], tuple(journal.get("legacy_tags") or ())
+                )
+                recovered = {"op": "uninstall", "forge_id": journal["forge_id"]}
+        except ContextError as exc:
+            # A poisoned journal must not wedge every later op: the redo hit a
+            # conflict that post-dates the crash (foreign doc, non-UTF-8 file).
+            # Quarantine the intent — evidence preserved — and report it,
+            # instead of failing forever on the same journal.
+            _quarantine(jpath, now.replace(":", ""))
+            _txn_drop(ctx)
+            return {
+                "op": str(journal.get("op") or "?"),
+                "quarantined": True,
+                "error": f"{exc.kind}: {exc.detail}",
+            }
         if recovered is None:
             _quarantine(jpath, now.replace(":", ""))
             _txn_drop(ctx)
@@ -1685,8 +1748,16 @@ def repair_context(root: Path | str) -> dict[str, Any]:
         now = _utc_now()
         previous = {e["forge_id"]: e for e in reg["forges"]}
         entries = []
+        invalid: list[dict[str, Any]] = []
         for fid in sorted(manifests):
             doc = manifests[fid]
+            # A capability file that fails schema validation is reported and
+            # kept out of the rebuilt registry — never an untyped crash on
+            # the one path meant to converge a broken context.
+            problems = validate_manifest(doc)
+            if problems:
+                invalid.append({"forge_id": fid, "problems": problems[:5]})
+                continue
             cap_sha = _sha_file(ctx / CAPABILITIES_DIR / f"{fid}.json")
             entries.append(_entry_from_manifest(doc, cap_sha, previous.get(fid), now))
         reg["forges"] = entries
@@ -1698,7 +1769,8 @@ def repair_context(root: Path | str) -> dict[str, Any]:
         # foreign-installer content is never ours to remove.
     return {
         "status": "repaired",
-        "forges": sorted(manifests),
+        "forges": sorted(e["forge_id"] for e in entries),
+        "invalid": invalid,
         "recovered": recovered,
         "notes": notes,
         "written": written,

{platformforge-0.2.1 → platformforge-0.2.3}/platformforge/_installkit.py

@@ -18,24 +18,27 @@ silently degrading.
 
 from __future__ import annotations
 
+import contextlib
 import hashlib
 import json
 import os
 import platform
 import re
+import stat
 import sys
 import tempfile
 import time
+import uuid
 from importlib import metadata as importlib_metadata
 from collections.abc import Callable
 from dataclasses import dataclass, field
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import Any
 
-_INSTALLKIT_VERSION = "1.0.2"
+_INSTALLKIT_VERSION = "1.0.4"
 # Filled by the vendor step (scripts/installkit/vendor.py) — the sha256 of
 # the canonical source body, so drift checks can compare vendored copies.
-_SOURCE_SHA256 = "a15ca78bb34a0109"
+_SOURCE_SHA256 = "7a51eb0c03d7a342"
 
 SCHEMA_MANIFEST = "forge/InstallationManifest/v1"
 SCHEMA_RECEIPT = "forge/InstallReceipt/v1"
@@ -67,6 +70,7 @@ E_DRIFT = "FORGE-INSTALL-DRIFT-UNREPAIRABLE"
 E_UNSUPPORTED = "FORGE-INSTALL-UNSUPPORTED"
 E_SPAWN = "FORGE-INSTALL-SPAWN-DISABLED"
 E_VERIFY = "FORGE-INSTALL-VERIFY-FAILED"
+E_UNSAFE = "FORGE-INSTALL-UNSAFE-PATH"
 E_WRITE = "FORGE-INSTALL-WRITE-FAILED"
 
 
@@ -125,16 +129,37 @@ def _sha_file(path: Path) -> str:
 
 def _atomic_write(path: Path, data: bytes) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
+    # Preserve the existing file's mode — mkstemp always creates 0600, and
+    # silently downgrading a user's 0644 doc is a destructive side effect.
+    mode = stat.S_IMODE(path.stat().st_mode) if path.is_file() else None
     fd, tmp = tempfile.mkstemp(prefix=path.name, dir=str(path.parent))
     try:
         with os.fdopen(fd, "wb") as fh:
             fh.write(data)
+            fh.flush()
+            os.fsync(fh.fileno())
+        if mode is not None:
+            os.chmod(tmp, mode)
         os.replace(tmp, path)
     finally:
         if os.path.exists(tmp):
             os.unlink(tmp)
 
 
+_SAFE_REL_RE = re.compile(r"^(?!/)(?!~)[A-Za-z0-9._][A-Za-z0-9_./-]*$")
+
+
+def _safe_rel(rel: str) -> bool:
+    """A ledger/asset relative path must stay inside the install root: no
+    ``..`` segments, no absolute/drive forms, no backslashes."""
+    return (
+        bool(_SAFE_REL_RE.match(rel))
+        and "\\" not in rel
+        and not any(part == ".." for part in PurePosixPath(rel).parts)
+        and not re.match(r"^[A-Za-z]:", rel)
+    )
+
+
 def _json_bytes(doc: dict[str, Any]) -> bytes:
     return (json.dumps(doc, indent=2, sort_keys=True) + "\n").encode("utf-8")
 
@@ -291,6 +316,9 @@ class Ledger:
         keys are user content); every other entry is compared by sha256."""
         out = []
         for rel, e in sorted(self.doc["entries"].items()):
+            if not _safe_rel(rel):
+                out.append({"path": rel, "status": "unsafe"})
+                continue
             p = root / rel
             if not p.exists():
                 out.append({"path": rel, "status": "missing"})
@@ -360,6 +388,7 @@ class _Lock:
     def __init__(self, lock: Path, stale_after_s: float = 900.0) -> None:
         self._lock = lock
         self._stale = stale_after_s
+        self._token = uuid.uuid4().hex
         self.held = False
         self.recovered = False
 
@@ -379,14 +408,23 @@ class _Lock:
                     E_LOCKED, f"install lock at {self._lock} could not be reclaimed"
                 ) from exc
             self.recovered = True
-            self._create()
+            try:
+                self._create()
+            except FileExistsError:
+                # A third party won the reclaim race — that is a normal lock
+                # contention outcome, not an internal error.
+                raise LockError(
+                    E_LOCKED, f"install lock at {self._lock} re-acquired during reclaim"
+                ) from None
             return self
 
     def _create(self) -> None:
         fd = os.open(str(self._lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
         os.write(
             fd,
-            _json_bytes({"pid": os.getpid(), "created_at": _utc_now()}),
+            _json_bytes(
+                {"pid": os.getpid(), "token": self._token, "created_at": _utc_now()}
+            ),
         )
         os.close(fd)
         self.held = True
@@ -419,11 +457,17 @@ class _Lock:
         return age > self._stale
 
     def __exit__(self, *exc: object) -> None:
-        if self.held:
-            try:
-                self._lock.unlink()
-            except OSError:
-                pass
+        try:
+            if self.held:
+                holder = _load_json(self._lock)
+                # Only remove the lock file when it still carries our token —
+                # after a stale reclaim the on-disk lock may belong to a
+                # newer claimant, and unlinking it would admit a third.
+                if isinstance(holder, dict) and holder.get("token") == self._token:
+                    with contextlib.suppress(OSError):
+                        self._lock.unlink()
+        finally:
+            self.held = False
 
 
 def acquire_lock(state_dir: Path, timeout_s: float = 0.0) -> _Lock:
@@ -677,6 +721,11 @@ def plan(ctx: InstallContext) -> dict[str, Any]:
         kind = _asset_kind(rel)
         if kind not in kinds:
             continue
+        if not _safe_rel(rel):
+            raise InstallError(
+                E_UNSAFE,
+                f"{rel!r}: escapes the install root — remove or fix the asset path",
+            )
         target = ctx.root / rel
         exists = target.exists()
         files.append(
@@ -786,6 +835,11 @@ def apply_install(ctx: InstallContext, *, approved: bool = False) -> dict[str, A
             kind = _asset_kind(rel)
             if kind not in kinds:
                 continue
+            if not _safe_rel(rel):
+                raise InstallError(
+                    E_UNSAFE,
+                    f"{rel!r}: escapes the install root — remove or fix the asset path",
+                )
             data = assets[rel]
             if kind in ("skill", "agent"):
                 ctx_bytes[kind] += len(data)
@@ -1029,6 +1083,7 @@ def status(ctx: InstallContext) -> dict[str, Any]:
             "ok": ok,
             "modified": [d for d in bad if d["status"] == "modified"],
             "missing": [d for d in bad if d["status"] == "missing"],
+            "unsafe": [d for d in bad if d["status"] == "unsafe"],
         },
         "receipts": [r.name for r in receipts],
         "forge_portal": forge_portal_presence(),
@@ -1053,12 +1108,18 @@ def doctor(ctx: InstallContext) -> dict[str, Any]:
     )
     for d in ledger.drift(ctx.root, ctx.spec):
         if d["status"] != "ok":
+            unsafe = d["status"] == "unsafe"
             checks.append(
                 {
                     "id": f"drift:{d['path']}",
                     "status": "FAIL",
-                    "detail": d["status"],
-                    "repairable": True,
+                    "detail": (
+                        "unsafe — ledger key escapes the install root; "
+                        "repair skips it: edit or rebuild the ledger"
+                        if unsafe
+                        else d["status"]
+                    ),
+                    "repairable": not unsafe,
                 }
             )
     if ctx.spec.mcp_server_name:
@@ -1165,10 +1226,10 @@ def repair(ctx: InstallContext) -> dict[str, Any]:
     for d in drift:
         rel = d["path"]
         entry = ledger.get(rel)
-        target = ctx.root / rel
-        if entry is None:
+        if entry is None or not _safe_rel(rel):
             skipped.append(rel)
             continue
+        target = ctx.root / rel
         data = _repair_content(ctx, rel, entry, assets, target)
         if data is None:
             skipped.append(rel)
@@ -1216,6 +1277,11 @@ def uninstall(ctx: InstallContext, *, purge_state: bool = False) -> dict[str, An
     ledger = Ledger.load(ctx.state_dir)
     removed, kept = [], []
     for rel in ledger.owned_paths():
+        if not _safe_rel(rel):
+            # A poisoned ledger key must never resolve into an unlink outside
+            # the install root — keep it (and the entry) for repair/triage.
+            kept.append(rel)
+            continue
         target = ctx.root / rel
         if rel in ctx.spec.marker_files and target.exists():
             # marker files: excise the block, keep the file
@@ -1295,9 +1361,18 @@ def _prune_empty_dirs(root: Path, removed: list[str]) -> None:
     first non-empty ancestor or ``root``. User dirs are never touched —
     ``rmdir`` refuses on non-empty directories by design."""
     seen: set[Path] = set()
+    resolved_root = root.resolve()
     for rel in removed:
-        parent = (root / rel).parent
-        while parent != root and root in parent.parents and parent not in seen:
+        # Entries may be ledger-relative keys or already-absolute paths
+        # (detach receipts). Both must resolve INSIDE root before rmdir.
+        try:
+            fpath = Path(rel) if Path(rel).is_absolute() else root / rel
+            fpath.resolve().relative_to(resolved_root)
+        except (OSError, ValueError):
+            continue
+        parent = fpath.resolve().parent
+        while parent != resolved_root and resolved_root in parent.parents \
+                and parent not in seen:
             try:
                 parent.rmdir()
             except OSError: