fix(package): harden restart-safe lifecycle state

Author: ImperaZim

CHANGELOG.md

@@ -126,6 +126,10 @@ elprobe run <package>
   and a matching installed `package-state.yml` entry before PMMP can load it.
 - Boot cleanup now removes orphaned managed proxy folders whose package state
   was removed, preventing removed packages from reappearing on the next boot.
+- Generated package-backed proxies now record `loaded-at` and `loaded-path` in
+  their marker during bootstrap. EasyLibrary preserves that runtime marker when
+  refreshing proxy mounts, so staged install/update state is cleared only after
+  the matching package really booted.
 
 ### Standalone shadow guard and switch flow
 
@@ -161,8 +165,11 @@ elprobe run <package>
   data cleanup.
 - Kept update, remove and rollback restart-based. Loaded PHP code is not
   hot-unloaded from the current PMMP session.
-- Cleanup currently targets temporary data only. Installed package versions and
-  backups remain preserved for rollback safety.
+- Removal now blocks when another installed package still requires the target,
+  for example `libpacket` while `libcommand` is installed.
+- Cleanup targets only `.downloads`, `.staging`, `_incoming*` and `.incoming*`
+  temporary paths. Installed package versions and backups remain preserved for
+  rollback safety.
 - Validated the leaf-package remove/reinstall cycle with `libform`:
   remove while active, restart detached, reinstall from release asset, restart
   active again and pass `elprobe run libform`.
@@ -175,6 +182,8 @@ elprobe run <package>
 - Doctor reports missing, incomplete or divergent proxies with repair guidance.
 - Stale restart-required markers are cleared once the package-backed plugin is
   confirmed active.
+- Pending restart state now remains visible when an active runtime does not
+  match the staged package path or was loaded before the staged operation.
 - Doctor now treats missing required package dependencies as a problem only for
   packages that are installed/staged, so a clean server with available-but-not
   installed packages no longer reports false dependency failures.

changelogs/3.0.md

@@ -271,6 +271,134 @@ elprobe run libform
 functional=yes source=package-backed-plugin
 ```
 
+### Pending restart runtime marker hardening
+
+Package-backed proxy plugins are discovered by PMMP before EasyLibrary itself
+is enabled. That boot order matters.
+
+Before the hardening, this sequence could produce a false pending state:
+
+1. a package install/update was staged;
+2. the server restarted;
+3. the generated proxy plugin loaded the new package successfully;
+4. EasyLibrary refreshed the proxy mount marker after loading;
+5. the refresh rewrote `.easylib-package-plugin.json` without remembering that
+   the proxy had already booted.
+
+The status service could then still report:
+
+```text
+installed-pending-restart
+```
+
+even though PMMP had already loaded the package-backed plugin for the current
+session.
+
+The generated proxy now records runtime evidence in the marker:
+
+```json
+{
+  "loaded-at": 1781923400,
+  "loaded-path": ".../plugin_data/EasyLibrary/packages/libform/2.0.0"
+}
+```
+
+When EasyLibrary refreshes hidden proxy mounts, it preserves those runtime
+fields instead of erasing them. The package status service now clears
+restart-required metadata only when both checks are true:
+
+- the active runtime path matches the staged package path;
+- the runtime loaded at or after the staged install/update/rollback timestamp.
+
+This avoids two bad states:
+
+- false pending restart after a successful restart;
+- false active state when a new package target was staged after the currently
+  loaded runtime.
+
+Validation performed with `libform`:
+
+```text
+/easylibrary packages install libform stable confirm
+restart
+/easylibrary packages status libform
+libform / LibForm v2.0.0 [active]
+- Restart-required markers were cleared because the package is active.
+
+/easylibrary packages doctor
+Packages: 13 / installed: 13 / active: 13 / pending restart: 0
+Problems: 0
+
+elprobe run libform
+functional=yes source=package-backed-plugin
+```
+
+### Dependency-safe removal
+
+Remove is now dependency-aware for installed packages.
+
+Example:
+
+```text
+/easylibrary packages remove libpacket
+```
+
+If `libcommand` is still installed and requires `LibPacket`, the command is
+blocked with a concrete reason:
+
+```text
+Cannot remove while installed packages require it: LibCommand.
+Remove or migrate those dependent packages first, then retry this command.
+```
+
+Why this matters:
+
+- `remove` is restart-based, so breaking the next boot is easy if a dependency
+  disappears silently;
+- package-backed plugins participate in PMMP `depend` resolution;
+- the package manager must refuse an unsafe detach before writing state.
+
+This guard is intentionally conservative. It checks installed package manifests
+and blocks removal when another installed package declares the target as a hard
+dependency.
+
+### Temporary cleanup allowlist
+
+Cleanup was narrowed to package-manager temporary paths only.
+
+It now targets:
+
+```text
+.downloads
+.staging
+_incoming*
+.incoming*
+```
+
+It intentionally preserves:
+
+```text
+packages/<id>/<version>/
+.backups/
+```
+
+Why this matters:
+
+- installed package versions are active or rollback candidates;
+- `.backups` is part of rollback safety;
+- interrupted downloads/staging folders should be disposable;
+- accidental broad cleanup should not remove usable packages.
+
+Validation:
+
+```text
+/easylibrary packages cleanup
+/easylibrary packages cleanup confirm
+```
+
+The dry-run and apply output both mention the allowlist and state that installed
+package versions and backups are preserved.
+
 ### Release asset install validation
 
 The full package-backed server was rebuilt from official GitHub Release
@@ -955,6 +1083,7 @@ Cleanup currently removes temporary package manager data only:
 .downloads
 .staging
 _incoming*
+.incoming*
 ```
 
 Installed package versions and `.backups` are preserved because backups are part

src/imperazim/library/command/subcommand/packages/DoctorPackagesSubCommand.php

@@ -57,6 +57,7 @@ protected function run(CommandResult $result): void {
         foreach ($doctor['statuses'] as $status) {
             if ($status->getState() !== PackageInstallState::INSTALLED_SHADOWED_BY_STANDALONE
                 && $status->getState() !== PackageInstallState::INSTALLED_DISABLED
+                && $status->getState() !== PackageInstallState::INSTALLED_PENDING_RESTART
                 && $status->getState() !== PackageInstallState::ACTIVE) {
                 continue;
             }

src/imperazim/library/package/PackageAutoloadManager.php

@@ -76,7 +76,7 @@ public function enableInstalledPackages(): void {
 
             try {
                 $this->enablePackage($source, $path);
-                PackageRuntimeRegistry::markActive($source->getId());
+                PackageRuntimeRegistry::markActive($source->getId(), $path);
                 $this->host->getLogger()->info('[PackageManager] Internal package active: ' . $source->getName() . ' v' . $status->getInstalledVersion());
             } catch (Throwable $throwable) {
                 $this->unregisterPackageAutoloaders($source->getId());

src/imperazim/library/package/PackageCleanupService.php

@@ -53,7 +53,11 @@ public function cleanupTemporary(bool $confirmed): PackageCleanupReport {
             }
 
             if (is_dir($target)) {
-                $this->removeDirectoryContents($target);
+                if ($this->isIncomingRelativePath($label)) {
+                    $this->removeDirectory($target);
+                } else {
+                    $this->removeDirectoryContents($target);
+                }
             } else {
                 @unlink($target);
             }
@@ -63,6 +67,7 @@ public function cleanupTemporary(bool $confirmed): PackageCleanupReport {
         if (!$report->hasChanges()) {
             $report->addNote('No temporary package downloads, staging folders or _incoming artifacts were found.');
         }
+        $report->addNote('Cleanup allowlist: .downloads, .staging, _incoming* and .incoming* only.');
         $report->addNote('Installed package versions and .backups are intentionally preserved.');
 
         return $report;
@@ -121,7 +126,11 @@ private function isSafeCleanupTarget(string $packagesDirectory, string $target):
         $relative = $this->relativePath($root, $path);
         return $relative === '.downloads'
             || $relative === '.staging'
-            || str_starts_with($relative, '_incoming')
+            || $this->isIncomingRelativePath($relative);
+    }
+
+    private function isIncomingRelativePath(string $relative): bool {
+        return str_starts_with($relative, '_incoming')
             || str_starts_with($relative, '.incoming');
     }
 
@@ -174,4 +183,9 @@ private function removeDirectoryContents(string $path): void {
             @unlink($file->getPathname());
         }
     }
+
+    private function removeDirectory(string $path): void {
+        $this->removeDirectoryContents($path);
+        @rmdir($path);
+    }
 }

src/imperazim/library/package/PackagePluginLoader.php

@@ -44,7 +44,7 @@ public function loadPlugin(string $file): void {
         }
 
         $this->registerPackageSourcePath($source, $path);
-        PackageRuntimeRegistry::markActive($source->getId());
+        PackageRuntimeRegistry::markActive($source->getId(), $path);
     }
 
     public function getPluginDescription(string $file): ?PluginDescription {

src/imperazim/library/package/PackagePluginMountManager.php

@@ -18,6 +18,7 @@
 use function is_array;
 use function is_dir;
 use function is_file;
+use function is_numeric;
 use function is_string;
 use function json_decode;
 use function json_encode;
@@ -330,6 +331,7 @@ private function writeMount(PackageSource $source, string $packagePath, string $
             throw new RuntimeException('Cannot create plugin mount directory: ' . $mount);
         }
 
+        $previousMarker = $this->readMarker($mount);
         $manifest = $this->readManifest($packagePath);
         $manifest->assertMatches($source, $version);
 
@@ -358,6 +360,7 @@ private function writeMount(PackageSource $source, string $packagePath, string $
             'manifest-state' => $standalonePresent ? 'parked-standalone-present' : 'active',
             'managed-by' => 'EasyLibrary',
         ];
+        $this->preserveRuntimeMarker($previousMarker, $payload);
         file_put_contents($mount . DIRECTORY_SEPARATOR . self::MARKER_FILE, json_encode($payload, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . "\n");
 
         $readyManifest = $mount . DIRECTORY_SEPARATOR . self::READY_PLUGIN_YML;
@@ -381,6 +384,30 @@ private function writeMount(PackageSource $source, string $packagePath, string $
         }
     }
 
+    /**
+     * Proxy plugins are loaded before EasyLibrary can refresh hidden mounts.
+     * Keep the runtime marker from that early proxy load so status/doctor can
+     * decide whether a staged package already took effect after restart.
+     *
+     * @param array<string, mixed>|null $previousMarker
+     * @param array<string, mixed>      $payload
+     */
+    private function preserveRuntimeMarker(?array $previousMarker, array &$payload): void {
+        if ($previousMarker === null || !is_numeric($previousMarker['loaded-at'] ?? null)) {
+            return;
+        }
+
+        $payload['loaded-at'] = (int) $previousMarker['loaded-at'];
+        if (is_string($previousMarker['loaded-path'] ?? null)) {
+            $payload['loaded-path'] = $previousMarker['loaded-path'];
+            return;
+        }
+
+        if (is_string($previousMarker['path'] ?? null)) {
+            $payload['loaded-path'] = $previousMarker['path'];
+        }
+    }
+
     private function readManifest(string $packagePath): PackageManifest {
         $path = $packagePath . DIRECTORY_SEPARATOR . 'package.yml';
         if (!is_file($path)) {
@@ -515,6 +542,7 @@ private function proxyClassTemplate(): string {
 use function is_file;
 use function is_string;
 use function json_decode;
+use function json_encode;
 use function ltrim;
 use function method_exists;
 use function rtrim;
@@ -526,7 +554,10 @@ private function proxyClassTemplate(): string {
 use function str_starts_with;
 use function strlen;
 use function substr;
+use function time;
 use function trim;
+use const JSON_PRETTY_PRINT;
+use const JSON_THROW_ON_ERROR;
 
 final class __PROXY_CLASS__ extends PluginBase {
 
@@ -587,6 +618,10 @@ private function bootstrap(): void {
             throw new RuntimeException('EasyLibrary package path is missing or unavailable: ' . $packagePath);
         }
 
+        $data['loaded-at'] = time();
+        $data['loaded-path'] = $packagePath;
+        file_put_contents($markerPath, json_encode($data, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . "\n");
+
         $this->marker = $data;
         $this->registerPackageAutoloaders($packagePath, $data);
         $this->entry = $this->createEntry($data);

src/imperazim/library/package/PackageRemoveService.php

@@ -30,7 +30,7 @@ public function remove(PackageSource $source, bool $confirmed): PackageRemoveRep
         if ($state !== []) {
             $requiredDependents = $this->installedDependents($source, false);
             if ($requiredDependents !== []) {
-                $report->block('Cannot remove while installed packages require it: ' . implode(', ', $requiredDependents) . '. Remove dependent packages first.');
+                $report->block('Cannot remove while installed packages require it: ' . implode(', ', $requiredDependents) . '. Remove or migrate those dependent packages first, then retry this command.');
                 return $report;
             }