lean-runtime 2.6.1__tar.gz → 2.6.2__tar.gz

{lean_runtime-2.6.1 → lean_runtime-2.6.2}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 2.6.2 - 2026-08-14
+
+- Keep an existing initialization target's directory inode alive, so running
+  `lean-runtime init .` no longer strands the invoking shell in an unlinked
+  working directory. Fully prepared staged children are published with rollback
+  while Git metadata, custom agent guidance, and index state remain in place.
+- Make attachment plans distinguish checkout bytes removed, compatible shared
+  bytes already available, new shared bytes required, and estimated machine
+  recovery. Exact managed packages now bypass redundant source resolution when
+  their toolchain, platform, revision, and effective dependency closure match.
+- Emit package-by-package shared-workspace resolution, reuse, and import events,
+  and add `lean-runtime --version`.
+
 ## 2.6.1 - 2026-08-14
 
 - Allow `lean-runtime init .` at an otherwise empty Git repository root while

{lean_runtime-2.6.1/lean_runtime.egg-info → lean_runtime-2.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.6.1
+Version: 2.6.2
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -213,6 +213,8 @@ For a new project, the target may be absent, empty, or an otherwise empty Git
 repository root; existing Git identity and index state are preserved. A custom
 `AGENTS.md` is also allowed and retained. Other existing contents are rejected
 before acquisition rather than overwritten.
+An existing target directory remains the same live directory, so `init .` does
+not invalidate the invoking shell's working directory.
 When the directory spelling is not the intended Lean module capitalization,
 set it explicitly, for example `lean-runtime init . --name IntegralFramework`.
 

{lean_runtime-2.6.1 → lean_runtime-2.6.2}/README.md

@@ -177,6 +177,8 @@ For a new project, the target may be absent, empty, or an otherwise empty Git
 repository root; existing Git identity and index state are preserved. A custom
 `AGENTS.md` is also allowed and retained. Other existing contents are rejected
 before acquisition rather than overwritten.
+An existing target directory remains the same live directory, so `init .` does
+not invalidate the invoking shell's working directory.
 When the directory spelling is not the intended Lean module capitalization,
 set it explicitly, for example `lean-runtime init . --name IntegralFramework`.
 

{lean_runtime-2.6.1 → lean_runtime-2.6.2}/docs/cli.md

@@ -176,11 +176,18 @@ recursive mode inventories a project tree, reports blockers and estimated disk
 recovery, and adopts each valid project transactionally. `detach` is likewise a
 preview unless `--execute` is present. Attached projects use shared mode by
 default in `lean-runtime build`; detach before requesting `--local`.
+The attachment preview separates bytes removed from each checkout, compatible
+bytes already present in the shared store, new shared bytes that must be
+imported, and estimated machine-level recovery. These quantities differ on a
+first attachment because copy-on-write migration can shrink the repository
+without immediately freeing the dependency blocks retained by the shared copy.
 
 A new `init` target may be absent, empty, or an otherwise empty Git root, with
 an optional existing `AGENTS.md`. Git metadata and the custom guide are
 preserved. Planning rejects any other existing contents using the same
 validation as execution.
+Existing target directories are populated in place after staging verifies, so
+`lean-runtime init .` keeps the caller's current working directory valid.
 `--name NAME` overrides the inferred Lake package/root module name for a new
 project, which is useful when a lowercase repository name needs internal
 capitalization such as `IntegralFramework`.

{lean_runtime-2.6.1 → lean_runtime-2.6.2}/docs/getting-started.md

@@ -48,6 +48,8 @@ empty Git repository root. In the Git case, `init` preserves the existing HEAD,
 index, remotes, and worktree metadata. It also preserves an existing
 `AGENTS.md`; any other non-project contents are rejected by both `--plan` and
 execution rather than overwritten.
+If the target already exists, initialization keeps that directory inode alive;
+the shell that runs `lean-runtime init .` can immediately continue using it.
 The directory name normally supplies the Lake package/root module name. Override
 it when capitalization matters, for example:
 

{lean_runtime-2.6.1 → lean_runtime-2.6.2}/docs/local-projects.md

@@ -69,10 +69,12 @@ toolchain is rejected under `--offline` or `--max-download` rather than silently
 bypassing the policy.
 
 An otherwise empty Git root is a valid new-project target. The original `.git`
-directory—or `.git` worktree file—is transferred through the atomic publication
-without changing HEAD, the index, or remotes. A pre-existing `AGENTS.md` is also
-preserved. Other contents must be moved first or represented by an existing
-pinned Lake project; the read-only plan enforces the same rule as execution.
+directory—or `.git` worktree file—stays in place without changing HEAD, the
+index, or remotes. The existing directory inode also stays live, so invoking
+`lean-runtime init .` does not strand the shell in an unlinked working
+directory. A pre-existing `AGENTS.md` is preserved. Other contents must be moved
+first or represented by an existing pinned Lake project; the read-only plan
+enforces the same rule as execution.
 Use `--name NAME` when creating inside a lowercase or otherwise differently
 named repository and the Lean root module needs an explicit spelling.
 
@@ -106,13 +108,15 @@ lean-runtime attach ~/research --recursive
 lean-runtime attach ~/research --recursive --execute
 ```
 
-The preview groups exact graphs, reports current and estimated shared storage,
-and identifies missing local paths, dirty dependencies, and revision
-mismatches. Execution continues through independent projects while reporting
-per-project failures. It first prepares the exact shared workspace and probes it
-through Lake. Only then does it atomically replace `.lake/packages` with package
-links, probe the resulting project through ordinary Lake, and discard the old
-generated copies. Any failure restores the original package directory.
+The preview groups exact graphs and separately reports checkout bytes removed,
+compatible shared bytes already ready, new shared bytes required, and estimated
+machine-level recovery. It also identifies missing local paths, dirty
+dependencies, and revision mismatches. Execution continues through independent
+projects while reporting per-project failures. It first prepares the exact
+shared workspace and probes it through Lake. Only then does it atomically
+replace `.lake/packages` with package links, probe the resulting project through
+ordinary Lake, and discard the old generated copies. Any failure restores the
+original package directory.
 
 The project itself remains portable. To return to independent package copies:
 
@@ -151,12 +155,20 @@ their artifacts.
 
 The first shared build imports a clean, revision-matching local dependency copy
 when one exists, using copy-on-write filesystem clones where supported. Missing
-sources are fetched at the exact manifest commit. A plain shared build never
+sources are fetched at the exact manifest commit. A later project bypasses
+source resolution when a managed package marker proves that its toolchain,
+platform, revision, and effective dependency closure already match. A plain shared build never
 deletes the old `.lake/packages`; only an explicit `attach --execute` replaces
 those generated copies after verification. `lean-runtime storage` reports
 shared project package usage; automatic cleanup of those packages is not yet
 implemented.
 
+Check capsules and mutable shared packages are intentionally separate storage
+tiers. Capsules are source-free and trimmed for checking; ordinary Lake
+development needs source-shaped packages and build metadata. A capsule can seed
+compatible build artifacts while the exact source workspace is materialized,
+but attached projects ultimately link to the mutable shared-project store.
+
 This mode requires a manifest and never runs `lake update`, so it cannot silently
 change dependency revisions. It also reuses an existing local Git object database
 when that database contains another requested revision, avoiding redundant Git

{lean_runtime-2.6.1 → lean_runtime-2.6.2}/lean_runtime/cli.py

@@ -7,6 +7,7 @@ import json
 import sys
 import time
 from datetime import datetime
+from importlib.metadata import version as distribution_version
 from pathlib import Path
 from typing import Any
 
@@ -172,9 +173,12 @@ def _render_adoption_plan(plan: AdoptionPlan) -> None:
         for warning in project.warnings:
             print(f"           note: {warning}")
     print()
-    print(f"Current dependency copies: {format_byte_size(plan.current_dependency_bytes)}")
-    print(f"Estimated shared copies:   {format_byte_size(plan.estimated_shared_bytes)}")
-    print(f"Potential recovery:        {format_byte_size(plan.estimated_reclaimable_bytes)}")
+    print(f"Checkout bytes removed:    {format_byte_size(plan.checkout_bytes_removed)}")
+    print(f"Shared bytes already ready:{format_byte_size(plan.shared_bytes_reused):>10}")
+    print(f"New shared bytes needed:   {format_byte_size(plan.new_shared_bytes)}")
+    print(
+        f"Estimated machine recovery: {format_byte_size(plan.estimated_machine_reclaimable_bytes)}"
+    )
 
 
 def _render_init_plan(plan: ProjectInitPlan) -> None:
@@ -280,6 +284,11 @@ def _add_policy(parser: argparse.ArgumentParser, *, timeout: float = 120) -> Non
 
 def parser() -> argparse.ArgumentParser:
     root = argparse.ArgumentParser(prog="lean-runtime")
+    root.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {distribution_version('lean-runtime')}",
+    )
     root.add_argument("--home", help="runtime store root")
     root.add_argument("--quiet", action="store_true", help="suppress progress events")
     root.add_argument("--verbose", action="store_true", help="show detailed decisions and checks")
@@ -747,7 +756,11 @@ def main(argv: list[str] | None = None) -> int:
                     _render_adoption_plan(adoption_plan)
                     print("No changes made. Re-run with --execute to adopt shared packages.")
                 return 0 if adoption_plan.blocked == 0 else 1
-            adoption_result = runtime.attach_projects(args.path, recursive=args.recursive)
+            adoption_result = runtime.attach_projects(
+                args.path,
+                recursive=args.recursive,
+                plan=adoption_plan,
+            )
             if args.json:
                 _json(adoption_result.to_dict())
             else:

{lean_runtime-2.6.1 → lean_runtime-2.6.2}/lean_runtime/project_sharing.py

@@ -156,6 +156,8 @@ class AdoptionPlan:
     recursive: bool
     current_dependency_bytes: int
     estimated_shared_bytes: int
+    shared_bytes_reused: int = 0
+    new_shared_bytes: int = 0
 
     @property
     def ready(self) -> int:
@@ -167,7 +169,16 @@ class AdoptionPlan:
 
     @property
     def estimated_reclaimable_bytes(self) -> int:
-        return max(0, self.current_dependency_bytes - self.estimated_shared_bytes)
+        """Compatibility alias for estimated machine-level recovery."""
+        return self.estimated_machine_reclaimable_bytes
+
+    @property
+    def checkout_bytes_removed(self) -> int:
+        return self.current_dependency_bytes
+
+    @property
+    def estimated_machine_reclaimable_bytes(self) -> int:
+        return max(0, self.current_dependency_bytes - self.new_shared_bytes)
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -177,6 +188,10 @@ class AdoptionPlan:
             "blocked": self.blocked,
             "current_dependency_bytes": self.current_dependency_bytes,
             "estimated_shared_bytes": self.estimated_shared_bytes,
+            "checkout_bytes_removed": self.checkout_bytes_removed,
+            "shared_bytes_reused": self.shared_bytes_reused,
+            "new_shared_bytes": self.new_shared_bytes,
+            "estimated_machine_reclaimable_bytes": (self.estimated_machine_reclaimable_bytes),
             "estimated_reclaimable_bytes": self.estimated_reclaimable_bytes,
         }
 
@@ -402,10 +417,16 @@ def inspect_adoption(root: Path) -> ProjectAdoption:
     )
 
 
-def plan_adoption(path: Path, *, recursive: bool) -> AdoptionPlan:
+def plan_adoption(
+    path: Path,
+    *,
+    recursive: bool,
+    shared: SharedProjectManager | None = None,
+) -> AdoptionPlan:
     roots = discover_shareable_projects(path, recursive=recursive)
     projects = tuple(inspect_adoption(root) for root in roots)
     groups: dict[str, int] = {}
+    reused_groups: set[str] = set()
     for project in projects:
         if not project.ready or project.attached:
             continue
@@ -417,6 +438,15 @@ def plan_adoption(path: Path, *, recursive: bool) -> AdoptionPlan:
             str(entry["name"]): _entry_identity(identity_entry)
             for entry, identity_entry in zip(entries, identity_entries, strict=True)
         }
+        reusable = (
+            shared.reusable_packages(
+                context,
+                entries,
+                effective_entries=effective_entries,
+            )
+            if shared is not None
+            else {}
+        )
         package_dir = _packages_directory(context)
         for entry in entries:
             if entry["type"] != "git":
@@ -425,23 +455,30 @@ def plan_adoption(path: Path, *, recursive: bool) -> AdoptionPlan:
             local_bytes = _tree_bytes(local)
             subdir = entry.get("subDir")
             source_package = local / subdir if isinstance(subdir, str) and subdir else local
-            if _git_head(local) == entry.get("rev") and source_package.is_dir():
+            reusable_package = reusable.get(str(entry["name"]))
+            if reusable_package is not None:
+                key = reusable_package.name
+                reused_groups.add(key)
+            elif _git_head(local) == entry.get("rev") and source_package.is_dir():
                 identity = _package_identity(
                     context=context,
                     entry=entry,
                     source_package=source_package,
                     effective_entries=effective_entries,
                 )
+                key = sha256_id("project_package", identity)
             else:
                 identity = {
                     "toolchain": context.toolchain,
                     "manifest": manifest,
                     "package": entry,
                 }
-            key = sha256_id("project_adoption_estimate", identity)
+                key = sha256_id("project_adoption_estimate", identity)
             groups[key] = max(groups.get(key, 0), local_bytes)
     current = sum(project.dependency_bytes for project in projects if not project.attached)
-    return AdoptionPlan(projects, recursive, current, sum(groups.values()))
+    reused = sum(size for key, size in groups.items() if key in reused_groups)
+    new = sum(size for key, size in groups.items() if key not in reused_groups)
+    return AdoptionPlan(projects, recursive, current, sum(groups.values()), reused, new)
 
 
 def plan_detachment(root: Path) -> DetachmentPlan:
@@ -499,6 +536,12 @@ class ProjectAdopter:
             seed_packages=seed_packages,
             seed_package_paths=seed_package_paths,
         )
+        self.shared.events.emit(
+            "project.attach.shared_probe_started",
+            f"Verifying shared graph for {context.root.name}",
+            phase="project-attach",
+            packages=len(workspace.package_ids),
+        )
         probe(workspace.overrides_file)
         manifest_packages = _manifest_packages(context)
         override_value = json.loads(workspace.overrides_file.read_text(encoding="utf-8"))
@@ -525,6 +568,13 @@ class ProjectAdopter:
         marker = lake_dir / ATTACHMENT_RECORD
         config = context.root / PROJECT_CONFIG
         try:
+            self.shared.events.emit(
+                "project.attach.swap_started",
+                f"Replacing local dependency copies for {context.root.name}",
+                phase="project-attach",
+                packages=len(workspace.package_ids),
+                checkout_bytes=reclaimed,
+            )
             for entry in manifest_packages:
                 if entry["type"] != "git":
                     continue
@@ -544,6 +594,12 @@ class ProjectAdopter:
                 packages_dir.replace(backup)
             staging.replace(packages_dir)
             swapped = True
+            self.shared.events.emit(
+                "project.attach.attached_probe_started",
+                f"Verifying attached graph for {context.root.name}",
+                phase="project-attach",
+                packages=len(workspace.package_ids),
+            )
             probe(None)
             record = {
                 "schema": ATTACHMENT_SCHEMA,
@@ -556,6 +612,13 @@ class ProjectAdopter:
             write_json_atomic(marker, record)
             config.write_text(_CONFIG_CONTENT, encoding="utf-8")
             _remove_path(backup)
+            self.shared.events.emit(
+                "project.attach.completed",
+                f"Attached shared dependencies for {context.root.name}",
+                phase="project-attach",
+                packages=len(workspace.package_ids),
+                checkout_bytes=reclaimed,
+            )
         except BaseException:
             _remove_path(staging)
             if swapped:

{lean_runtime-2.6.1 → lean_runtime-2.6.2}/lean_runtime/runtime.py

@@ -1167,7 +1167,7 @@ class Runtime:
         self, path: str | os.PathLike[str], *, recursive: bool = False
     ) -> AdoptionPlan:
         """Inspect one project or a tree without changing it."""
-        return plan_adoption(Path(path), recursive=recursive)
+        return plan_adoption(Path(path), recursive=recursive, shared=self.shared_projects)
 
     def _probe_project_graph(
         self,
@@ -1211,12 +1211,20 @@ class Runtime:
         recursive: bool = False,
         seed_packages: Path | None = None,
         seed_package_paths: dict[str, Path] | None = None,
+        plan: AdoptionPlan | None = None,
     ) -> AdoptionBatchResult:
         """Adopt exact shared dependencies after a read-only plan."""
-        plan = self.plan_project_adoption(path, recursive=recursive)
+        if plan is not None:
+            requested_roots = discover_shareable_projects(Path(path), recursive=recursive)
+            planned_roots = tuple(project.root for project in plan.projects)
+            if requested_roots != planned_roots or plan.recursive != recursive:
+                raise ProjectError("adoption plan does not match the requested project scope")
+            selected_plan = plan
+        else:
+            selected_plan = self.plan_project_adoption(path, recursive=recursive)
         results: list[AdoptionResult] = []
         failures: list[tuple[Path, str]] = []
-        for project in plan.projects:
+        for project in selected_plan.projects:
             if project.attached:
                 workspace_id = discover_project(project.root).provenance().workspace_id
                 results.append(
@@ -1242,15 +1250,15 @@ class Runtime:
                     self.project_adopter.attach(
                         context,
                         probe=probe,
-                        seed_packages=seed_packages if len(plan.projects) == 1 else None,
+                        seed_packages=(seed_packages if len(selected_plan.projects) == 1 else None),
                         seed_package_paths=(
-                            seed_package_paths if len(plan.projects) == 1 else None
+                            seed_package_paths if len(selected_plan.projects) == 1 else None
                         ),
                     )
                 )
             except (OSError, ProjectError) as exc:
                 failures.append((project.root, str(exc)))
-        return AdoptionBatchResult(plan, tuple(results), tuple(failures))
+        return AdoptionBatchResult(selected_plan, tuple(results), tuple(failures))
 
     def scan_projects(
         self, path: str | os.PathLike[str], *, recursive: bool = True
@@ -1791,10 +1799,10 @@ class Runtime:
         staging = Path(
             tempfile.mkdtemp(prefix=f".{target.name}.lean-runtime-init-", dir=target.parent)
         )
-        backup: Path | None = None
         published = False
         original_git = next((entry for entry in existing_entries if entry.name == ".git"), None)
-        git_transferred = False
+        published_in_place = False
+        published_entries: list[Path] = []
         try:
             custom_agents = target / "AGENTS.md"
             if custom_agents.is_file():
@@ -1890,41 +1898,47 @@ class Runtime:
                     remove_tree(generated_git)
                 elif generated_git.exists() or generated_git.is_symlink():
                     generated_git.unlink()
-                original_git.replace(generated_git)
-                git_transferred = True
             if target.exists():
-                backup = target.parent / f".{target.name}.lean-runtime-backup-{os.getpid()}"
-                target.replace(backup)
-            staging.replace(target)
+                # Keep an existing directory inode alive. Replacing the directory itself
+                # leaves a shell that invoked `lean-runtime init .` inside an unlinked cwd.
+                # Staging has already been fully initialized, attached, and probed, so only
+                # its children need a small rollback-safe publication transaction here.
+                published_in_place = True
+                for entry in sorted(staging.iterdir(), key=lambda path: path.name):
+                    destination = target / entry.name
+                    if destination.exists() or destination.is_symlink():
+                        if entry.name == "AGENTS.md" and destination.is_file():
+                            if entry.is_symlink() or entry.is_file():
+                                entry.unlink()
+                            elif entry.exists():
+                                remove_tree(entry)
+                            continue
+                        raise ProjectError(
+                            f"initialization target changed while publishing: {destination}"
+                        )
+                    entry.replace(destination)
+                    published_entries.append(destination)
+            else:
+                staging.replace(target)
             published = True
-            if backup is not None:
-                remove_tree(backup)
-                backup = None
             context = discover_project(target)
             # Registry discovery is an optimization, not part of publishing the project.
             with suppress(OSError, EnvironmentError):
                 self.shared_projects.remember_project(context)
             return replace(result.results[0], root=target)
         except BaseException:
-            if git_transferred:
-                staged_git = (target if published else staging) / ".git"
-                restore_root = backup if backup is not None and backup.exists() else target
-                if staged_git.exists() or staged_git.is_symlink():
-                    restore_root.mkdir(parents=True, exist_ok=True)
-                    staged_git.replace(restore_root / ".git")
-                git_transferred = False
-            if published:
-                if target.exists():
-                    remove_tree(target)
-                if backup is not None and backup.exists():
-                    backup.replace(target)
-                    backup = None
+            if published_in_place:
+                for entry in reversed(published_entries):
+                    if entry.is_symlink() or entry.is_file():
+                        entry.unlink()
+                    elif entry.exists():
+                        remove_tree(entry)
+            elif published and target.exists():
+                remove_tree(target)
             raise
         finally:
             if staging.exists():
                 remove_tree(staging)
-            if backup is not None and backup.exists():
-                remove_tree(backup)
 
     def project(
         self,