thoth-agents 0.5.0 → 0.6.0

package/README.md

@@ -65,7 +65,7 @@ The commands below install at **global/user scope**.
 | <a href="https://github.com/anomalyco/opencode"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/opencode-dark.svg"><img src="https://svgl.app/library/opencode.svg" alt="OpenCode logo" width="48" height="48"></picture></a><br>**OpenCode** | Native plugin, agent team, workflow skills, and memory setup. | `npx thoth-agents@latest install --agent=opencode` |
 | <a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="OpenAI logo — Codex" width="48" height="48"></a><br>**Codex** | Native plugin plus the required global agent and instruction setup. **Close Codex first.** | `npx thoth-agents@latest install --agent=codex` |
 | <a href="https://claude.com/product/claude-code"><img src="https://github.com/anthropics.png?size=120" alt="Anthropic logo — Claude Code" width="48" height="48"></a><br>**Claude Code** | Marketplace agents and skills, completed by the CLI's external skills and memory setup. **Run the prerequisites below first.** | `npx thoth-agents@latest install --agent=claude` |
-| <a href="https://github.com/earendil-works/pi"><img src="https://raw.githubusercontent.com/EremesNG/thoth-mem/master/img/pi.svg" alt="Pi logo" width="48" height="48"></a><br>**Pi** | Native package, five specialists, delegation and research extensions, workflow skills, and memory setup. **Recommended for the best experience.** | `npx thoth-agents@latest install --agent=pi` |
+| <a href="https://github.com/earendil-works/pi"><img src="https://raw.githubusercontent.com/EremesNG/thoth-mem/master/img/pi.svg" alt="Pi logo" width="48" height="48"></a><br>**Pi** | Native package, five specialists, delegation, research, theme, sidebar and background-task extensions, workflow skills, and memory setup. **Recommended for the best experience.** | `npx thoth-agents@latest install --agent=pi` |
 
 ### Claude Code prerequisites
 
@@ -83,8 +83,11 @@ claude plugin install thoth-agents@thoth-plugins --scope user
 
 Inside Pi, use `/subagents-model` to edit model and effort profiles for global
 and project subagent definitions. See [subagent profile configuration](docs/installation.md#configure-subagent-model-profiles-inside-pi).
-Use `/subagents-tools` to edit each specialist's explicit tool list, including
-registered active and inactive extension and MCP tools. Globs (including `*`) are
+Both commands are registered by pi-subagents on pi-core's shared list-editor
+shell, with native CSI-u/kitty and legacy navigation keys and wheel support in
+regular and fullscreen TUI mode. Use `/subagents-tools` to edit resolved global/project definitions' tool
+lists, including registered active and inactive extension and MCP tools. Thoth
+supplies managed-specialist validation and reset defaults through an optional adapter. Globs (including `*`) are
 manual advanced selections over all registered root tools; the panel preserves
 them read-only. Edit `disallowed_tools` manually for injected tools and trimming
 globs; only Oracle denies `ask_orchestrator` by default. See
@@ -93,14 +96,37 @@ globs; only Oracle denies `ask_orchestrator` by default. See
 Pi setup currently supports the default `~/.pi/agent` root. See the
 [Pi installation guide](docs/installation.md#pi) for runtime requirements,
 existing-package conflicts, and recovery. Thoth manages its separate Pi
-delegation runtime as package `@thoth-agents/pi-subagents` (`0.1.0`) through
-`npm:@thoth-agents/pi-subagents@>=0.1.0`. Existing `pi-subagents` and
+delegation runtime as package `@thoth-agents/pi-subagents` through
+`npm:@thoth-agents/pi-subagents@>=0.3.0`, the first release owning
+`/subagents-tools`. Upgrade both packages together and `/reload` if Pi reports
+missing or duplicate command ownership. Existing `pi-subagents` and
 `pi-subagents-j0k3r` installs need manual recovery through Pi's package manager
 before setup. Local checkout development uses `pnpm run setup:pi:local`, which
 points Pi at the fork under `pi-packages/pi-subagents`; publishing the fork is
 not required for that path. Pi extensions run with your user's system
 permissions; agent tool allowlists are not an OS sandbox.
 
+### Optional Pi provider extensions (manual install)
+
+The installer does **not** install or manage the Claude/Antigravity bridges or
+pi-openai-fast. Install only those you want, then restart Pi:
+
+```bash
+pi install npm:@thoth-agents/pi-claude-bridge
+pi install npm:@thoth-agents/pi-antigravity-bridge
+pi install npm:@thoth-agents/pi-openai-fast
+```
+
+Authenticate Claude Code or the `agy` CLI separately. Claude rate-limit events
+from root and child sessions share pi-core's process-wide, account-wide registry
+(not a bus channel); affected subagent rows/details show active warnings and reset
+times without changing task status. Quota is on demand: `/claude quota` uses an
+experimental SDK API without sending a prompt; `/agy quota` shows Antigravity
+usage. Antigravity costs are API-equivalent estimates from an explicit catalog
+mapping, not subscription charges. The theme marks the total `(sub)` by default
+for both `claude-bridge` and `antigravity`. See
+[provider commands and caveats](docs/installation.md#manual-pi-provider-extensions).
+
 For scopes, troubleshooting, or local checkout installation, see the
 [installation guide](docs/installation.md). Local Pi checkout installs keep
 thoth-mem setup separate.
@@ -245,13 +271,58 @@ do not prove those other pieces are current. Use `status` to inspect the last
 complete CLI-managed installation and follow any reported recovery actions.
 
 For Pi, the first-party `thoth-agents` package remains exact and receipt-verified.
-The five mandatory external extensions use stable minimum-only `>=` ranges, so
+The nine selected extensions use stable minimum-only `>=` ranges, so
 Pi's native package manager can update them independently without waiting for a
-Thoth release. Status validates each installed manifest's package name and
-SemVer floor; newer stable versions are healthy, while prerelease, malformed,
+Thoth release. Install and applied Update now include
+`@thoth-agents/pi-thoth-theme`, `@thoth-agents/pi-background-tasks` and
+`@thoth-agents/pi-sidebar` at `>=0.3.0`.
+Existing copies of these three packages from any source are preserved and verified
+without reinstalling when compatible; older copies are left untouched and block
+completion with manual upgrade guidance. Ambiguous sources fail closed. Status
+validates each installed manifest's package name and SemVer floor; newer stable
+versions are healthy, while prerelease, malformed,
 missing, or older versions are not. Re-running Install or applying Update
-migrates legacy exact external sources through Pi while preserving package
-resource filters and unrelated settings.
+migrates legacy exact sources for the other selected extensions through Pi while
+preserving package resource filters and unrelated settings.
+
+Subagents (v2) and background tasks (v1) publish summary-only snapshots through
+[pi-core's task channels](pi-packages/pi-core/README.md#task-summary-and-usage-channels).
+The status line uses `thoth:subagents:usage`, not the removed raw
+`thoth:subagent-usage` bus event. Upgrade pi-subagents and pi-thoth-theme to
+`>=0.3.0` together and `/reload` to retain subagent cost display; the usage
+checkpoint discriminator is unchanged.
+
+The shared Pi Work panel uses pi-core's v2 data-only provider contract and
+[discovery/action API](pi-packages/pi-core/README.md#discovery-and-actions).
+Upgrade pi-subagents, pi-background-tasks and pi-todo together to `>=0.3.0`, then
+`/reload`; first-owner arbitration hides incompatible sections in mixed v1/v2
+installs. Subagent state is v2; background state, usage, requests and Render KIT remain v1.
+
+The [Pi sidebar](pi-packages/pi-sidebar/README.md) adds read-only Session,
+Workspace, Cost and discovered Todos/Subagents/Background panels in fullscreen and
+regular mode. `/sidebar` toggles, `/sidebar panels` lists ids for show/hide/order
+commands, and `/sidebar resize` resizes. `/sidebar settings` edits panel order,
+visibility, startup and default width; `/sidebar cost` opens task-cost curves
+against elapsed time per task, labeled by display name or a short task-summary name.
+Themed Agents/Background headers show static status-icon counts, omitting zero
+counts (Todos keeps completed/total), and detail commands; Workspace shows a
+`~`-abbreviated path and tracked file/line changes versus HEAD. Agent metrics
+include all available metrics with semantic icons (ASCII labels) in shared
+aligned columns that wrap without dropping metrics, stably across digit changes. Only displayed source panels absorb their
+Work sections; hiding the sidebar restores them. Panel order/visibility and
+startup policy/default width live in `~/.pi/agent/thoth-sidebar.json`. Subagent
+state v2 adds up to 100 cost-ranked persisted session summaries in `history`. Private Pi layout seams
+have guarded fallback; regular mode covers the live viewport, not historical
+scrollback. Update related extensions together to avoid mixed old UI owners.
+
+Pi's question UI replaces the editor without covering chat. `Ctrl+]` collapses it
+to a one-line dock and returns input to the editor; during an active run, `Enter`
+queues a steering message without answering the question. `Ctrl+]` re-expands
+with answers and drafts preserved, and the open tool-call card shows collapsed
+state. While open, `Ctrl+]` shadows editor `jumpForward`; collapsed `Esc` belongs
+to the editor or focused overlay. History/detail overlays close back to the
+expanded question or otherwise the editor; collapse and teardown preserve
+visible foreign-overlay focus. See [question controls](pi-packages/pi-questions-user/README.md#keyboard-controls).
 
 ## Documentation
 

package/dist/{chunk-VUNYH263.js → chunk-7YCSKK2X.js}

@@ -16,7 +16,7 @@ import {
   savePiModelConfig,
   syncPiSpecialists,
   writePiManagedText
-} from "./chunk-V7HSGRMB.js";
+} from "./chunk-U7FNFTM5.js";
 import {
   ALL_AGENT_NAMES,
   CLAUDE_CODE_PROMPT_DIALECT,
@@ -7174,6 +7174,21 @@ import { createHash as createHash6 } from "crypto";
 import { existsSync as existsSync15, readFileSync as readFileSync14 } from "fs";
 import { basename as basename4, dirname as dirname11, isAbsolute as isAbsolute5, join as join13 } from "path";
 
+// src/cli/pi-install.ts
+import { spawnSync as spawnSync6 } from "child_process";
+import { createHash as createHash5 } from "crypto";
+import {
+  existsSync as existsSync14,
+  lstatSync as lstatSync4,
+  readdirSync as readdirSync3,
+  readFileSync as readFileSync13,
+  realpathSync as realpathSync3,
+  statSync as statSync3
+} from "fs";
+import { basename as basename3, dirname as dirname10, isAbsolute as isAbsolute4, join as join12, resolve as resolve8, sep as sep3 } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
+import { lt } from "semver";
+
 // src/cli/pi-external-package.ts
 import { readFileSync as readFileSync9, realpathSync as realpathSync2 } from "fs";
 import { isAbsolute as isAbsolute2, join as join7 } from "path";
@@ -7289,21 +7304,6 @@ function inspectPiExternalPackage(packages, spec, requireManagedSource = true) {
   };
 }
 
-// src/cli/pi-install.ts
-import { spawnSync as spawnSync6 } from "child_process";
-import { createHash as createHash5 } from "crypto";
-import {
-  existsSync as existsSync14,
-  lstatSync as lstatSync4,
-  readdirSync as readdirSync3,
-  readFileSync as readFileSync13,
-  realpathSync as realpathSync3,
-  statSync as statSync3
-} from "fs";
-import { basename as basename3, dirname as dirname10, isAbsolute as isAbsolute4, join as join12, resolve as resolve8, sep as sep3 } from "path";
-import { fileURLToPath as fileURLToPath5 } from "url";
-import { lt } from "semver";
-
 // src/cli/pi-git-source.ts
 import { resolve as resolve4, sep as sep2 } from "path";
 import hostedGitInfo from "hosted-git-info";
@@ -7945,9 +7945,9 @@ var PI_COMMAND_TIMEOUT_MS = 12e4;
 var PI_PACKAGE_SPECS = [
   {
     id: "delegation",
-    source: "npm:@thoth-agents/pi-subagents@>=0.1.0",
+    source: "npm:@thoth-agents/pi-subagents@>=0.3.0",
     packageName: "@thoth-agents/pi-subagents",
-    version: "0.1.0"
+    version: "0.3.0"
   },
   {
     id: "context7",
@@ -7969,15 +7969,36 @@ var PI_PACKAGE_SPECS = [
   },
   {
     id: "ask-user-question",
-    source: "npm:@thoth-agents/pi-questions-user@>=0.1.0",
+    source: "npm:@thoth-agents/pi-questions-user@>=0.3.0",
     packageName: "@thoth-agents/pi-questions-user",
-    version: "0.1.0"
+    version: "0.3.0"
   },
   {
     id: "todo",
-    source: "npm:@thoth-agents/pi-todo@>=0.1.0",
+    source: "npm:@thoth-agents/pi-todo@>=0.3.0",
     packageName: "@thoth-agents/pi-todo",
-    version: "0.1.0"
+    version: "0.3.0"
+  },
+  {
+    id: "theme",
+    source: "npm:@thoth-agents/pi-thoth-theme@>=0.3.0",
+    packageName: "@thoth-agents/pi-thoth-theme",
+    version: "0.3.0",
+    preserveUserCopy: true
+  },
+  {
+    id: "background-tasks",
+    source: "npm:@thoth-agents/pi-background-tasks@>=0.3.0",
+    packageName: "@thoth-agents/pi-background-tasks",
+    version: "0.3.0",
+    preserveUserCopy: true
+  },
+  {
+    id: "sidebar",
+    source: "npm:@thoth-agents/pi-sidebar@>=0.3.0",
+    packageName: "@thoth-agents/pi-sidebar",
+    version: "0.3.0",
+    preserveUserCopy: true
   }
 ];
 var PI_GREP_MCP_ENTRY = {
@@ -8096,6 +8117,47 @@ function getPiExternalPackageSpecs(options = {}) {
     (spec) => spec.id === "delegation" ? { ...spec, source: runtimePackageRoot } : spec
   );
 }
+function sourceHintsAtPackage(source, spec) {
+  return source.includes(
+    spec.packageName.split("/").at(-1) ?? spec.packageName
+  );
+}
+function hasPiResourceSelection(value) {
+  return ["prompts", "skills", "themes"].some(
+    (key) => Array.isArray(value[key]) && value[key].length > 0
+  );
+}
+function inspectPiSetupPackage(packages, spec, requireManagedSource = true) {
+  if (spec.preserveUserCopy) {
+    const unidentified = packages.find((candidate) => {
+      const manifest = configuredPackageManifest(candidate);
+      if (typeof manifest?.name === "string" && manifest.name.trim())
+        return false;
+      const pi = manifest?.pi;
+      const manifestIsResourceOnly = isRecord6(pi) && (pi.extensions === void 0 || Array.isArray(pi.extensions) && pi.extensions.length === 0) && hasPiResourceSelection(pi);
+      return sourceHintsAtPackage(candidate.source, spec) || !candidate.resourceOnly && !manifestIsResourceOnly;
+    });
+    if (unidentified)
+      return {
+        state: "drift",
+        source: unidentified.source,
+        installedPath: unidentified.installedPath,
+        reason: `installed manifest identity is unavailable for ${unidentified.source}${unidentified.installedPath ? ` at ${unidentified.installedPath}` : ""}`
+      };
+  }
+  return inspectPiExternalPackage(
+    packages,
+    spec,
+    requireManagedSource && !spec.preserveUserCopy
+  );
+}
+function piPreservedPackageRecovery(spec, evidence) {
+  if (!spec.preserveUserCopy || evidence.state !== "drift") return void 0;
+  const diagnostic = `Cannot preserve and verify ${spec.packageName}: ${evidence.reason}. Existing copies are left untouched.`;
+  if (evidence.version && evidence.source)
+    return `${diagnostic} Upgrade this copy to >=${spec.version} (for local/git sources, upgrade the checkout), or review its ownership and switch with: pi remove ${evidence.source} --no-approve, then pi install ${spec.source} --no-approve. Verify with pi list --no-approve and the installed manifest, then rerun setup.`;
+  return `${diagnostic} Inspect pi list --no-approve and the configured package manifests; resolve the package identity or source ambiguity, then rerun setup.`;
+}
 var PI_INCUMBENT_TODO_NAME = "@juicesharp/rpiv-todo";
 var PI_INCUMBENT_QUESTIONS_NAME = "@juicesharp/rpiv-ask-user-question";
 function piQuestionSourceName(source) {
@@ -8233,6 +8295,11 @@ function parsePiPackageSource(source, baseDir) {
   return gitPath ? { type: "git", path: gitPath } : { type: "local", path: source };
 }
 function resolvePiPackage(candidate, options, userSettings) {
+  const declaration = Array.isArray(userSettings.packages) ? userSettings.packages.find(
+    (entry) => isRecord6(entry) && entry.source === candidate.source
+  ) : void 0;
+  const resourceOnly = isRecord6(declaration) && Array.isArray(declaration.extensions) && declaration.extensions.length === 0 && hasPiResourceSelection(declaration);
+  candidate = { ...candidate, resourceOnly };
   if (candidate.installedPath) return candidate;
   const paths = resolvePiPaths(options);
   const baseDir = candidate.scope === "user" ? paths.piRoot : join12(resolve8(options.cwd ?? process.cwd()), ".pi");
@@ -8274,9 +8341,15 @@ function resolvePiListedPackages(output, options) {
         `Pi package manifest identity cannot be verified: malformed pi list source ${source}. Rerun pi list --no-approve and inspect the configured sources before setup.`
       );
   }
-  return packages.map(
-    (candidate) => resolvePiPackage(candidate, options, settings)
-  );
+  return packages.map((candidate) => {
+    if (candidate.scope === "project")
+      projectSettings ??= readJsonObject(join12(projectRoot, "settings.json"));
+    return resolvePiPackage(
+      candidate,
+      options,
+      candidate.scope === "project" ? projectSettings ?? {} : settings
+    );
+  });
 }
 function readPiProjectPackages(options) {
   const projectRoot = join12(resolve8(options.cwd ?? process.cwd()), ".pi");
@@ -8286,6 +8359,26 @@ function readPiProjectPackages(options) {
     options
   );
 }
+function resolvePiPreservationPackages(output, options) {
+  const listed = resolvePiListedPackages(output, options);
+  const paths = resolvePiPaths(options);
+  const configured = [
+    ...resolvePiConfiguredPackages(
+      readJsonObject(paths.settingsPath),
+      "user",
+      options
+    ),
+    ...readPiProjectPackages(options)
+  ];
+  return [
+    ...listed,
+    ...configured.filter(
+      (candidate) => !listed.some(
+        ({ scope, source }) => scope === candidate.scope && source === candidate.source
+      )
+    )
+  ];
+}
 function scanPiProjectInstalledIncumbents(options, configuredPackages) {
   const projectRoot = join12(resolve8(options.cwd ?? process.cwd()), ".pi");
   const incumbents = [];
@@ -8425,6 +8518,7 @@ function buildPiSetupPlan(options = {}) {
       );
     }
   }
+  let userPackages = [];
   let plannedQuestionRemovals = [];
   let subagentsConfigContent;
   let mcpContent;
@@ -8449,11 +8543,7 @@ function buildPiSetupPlan(options = {}) {
       );
     if (incumbentBlockers.length > 0)
       throw new Error(incumbentBlockers.join("\n"));
-    const userPackages = resolvePiConfiguredPackages(
-      userSettings,
-      "user",
-      options
-    );
+    userPackages = resolvePiConfiguredPackages(userSettings, "user", options);
     blockers.push(...piQuestionIdentityBlockers(userPackages));
     plannedQuestionRemovals = findPiIncumbentQuestions(userPackages);
     subagentsConfigContent = `${JSON.stringify(
@@ -8490,6 +8580,19 @@ function buildPiSetupPlan(options = {}) {
     blockers.push(error instanceof Error ? error.message : String(error));
   }
   blockers.push(...piQuestionIdentityBlockers(projectPackages));
+  for (const pkg of getPiExternalPackageSpecs(options)) {
+    if (!pkg.preserveUserCopy) continue;
+    const recovery = piPreservedPackageRecovery(
+      pkg,
+      inspectPiSetupPackage(
+        [...userPackages, ...projectPackages].filter(
+          ({ source, installedPath }) => installedPath !== void 0 || sourceHintsAtPackage(source, pkg)
+        ),
+        pkg
+      )
+    );
+    if (recovery) blockers.push(recovery);
+  }
   const projectIncumbentTodos = findPiIncumbentTodos(projectPackages);
   for (const incumbent of projectIncumbentTodos) {
     const location = incumbent.unmappedSource ? "was found in the project install roots" : `is configured in ${projectSettingsPath}`;
@@ -8542,7 +8645,7 @@ function buildPiSetupPlan(options = {}) {
     })),
     ...getPiExternalPackageSpecs(options).map((pkg) => ({
       kind: "package",
-      description: `Install and verify Pi package ${pkg.source}`,
+      description: pkg.preserveUserCopy ? `Install Pi package ${pkg.source} if absent; otherwise preserve and verify its user copy` : `Install and verify Pi package ${pkg.source}`,
       target: pkg.source,
       command: { command: "pi", args: ["install", pkg.source, "--no-approve"] }
     })),
@@ -8948,6 +9051,25 @@ function applyPiSetup(plan) {
         installedPackages,
         manualRecovery: identityRecovery
       };
+    const preservationPackages = resolvePiPreservationPackages(
+      before.stdout,
+      plan.options
+    );
+    for (const pkg of getPiExternalPackageSpecs(plan.options)) {
+      if (!pkg.preserveUserCopy) continue;
+      const evidence = inspectPiSetupPackage(preservationPackages, pkg, false);
+      const recovery = piPreservedPackageRecovery(pkg, evidence);
+      if (recovery)
+        return {
+          success: false,
+          changed,
+          diagnostics,
+          error: recovery,
+          failedStep: "preflight",
+          installedPackages,
+          manualRecovery: recovery
+        };
+    }
     const installed = execute("pi", ["install", desiredSource, "--no-approve"]);
     if (installed.exitCode !== 0)
       throw new Error(
@@ -9117,16 +9239,22 @@ function applyPiSetup(plan) {
         );
     }
     for (const pkg of getPiExternalPackageSpecs(plan.options)) {
+      const preserveUserCopy = pkg.preserveUserCopy === true;
       const beforeInstall = execute("pi", ["list", "--no-approve"]);
       if (beforeInstall.exitCode !== 0)
         throw new Error(
           `Unable to inspect ${pkg.packageName} before installation: ${beforeInstall.stderr.trim() || "pi list unavailable"}`
         );
-      const prior = inspectPiExternalPackage(
-        parsePiPackageList(beforeInstall.stdout),
+      const prior = inspectPiSetupPackage(
+        preserveUserCopy ? resolvePiPreservationPackages(beforeInstall.stdout, plan.options) : parsePiPackageList(beforeInstall.stdout),
         pkg,
         false
       );
+      const recovery = piPreservedPackageRecovery(pkg, prior);
+      if (recovery) {
+        manualRecovery = recovery;
+        throw new Error(recovery);
+      }
       const priorSourceMatches = prior.state === "installed" && prior.source !== void 0 && prior.installedPath !== void 0 && piExternalSourceMatches(
         {
           scope: "user",
@@ -9135,7 +9263,8 @@ function applyPiSetup(plan) {
         },
         pkg.source
       );
-      if (!priorSourceMatches) {
+      const preserving = preserveUserCopy && prior.state === "installed";
+      if (!preserving && !priorSourceMatches) {
         const result = execute("pi", ["install", pkg.source, "--no-approve"]);
         if (result.exitCode !== 0)
           throw new Error(
@@ -9143,12 +9272,15 @@ function applyPiSetup(plan) {
           );
       }
       const listed = execute("pi", ["list", "--no-approve"]);
-      const verified = listed.exitCode === 0 ? inspectPiExternalPackage(parsePiPackageList(listed.stdout), pkg) : {
+      const verified = listed.exitCode === 0 ? inspectPiSetupPackage(
+        preserveUserCopy ? resolvePiPreservationPackages(listed.stdout, plan.options) : parsePiPackageList(listed.stdout),
+        pkg
+      ) : {
         state: "drift",
         version: void 0,
         reason: listed.stderr.trim() || "pi list unavailable"
       };
-      if (prior.state === "installed" && verified.version !== void 0 && lt(verified.version, prior.version)) {
+      if (!preserveUserCopy && prior.state === "installed" && verified.version !== void 0 && lt(verified.version, prior.version)) {
         const restoreSource = prior.source ?? `npm:${pkg.packageName}@${prior.version}`;
         const restored = execute("pi", [
           "install",
@@ -9168,8 +9300,21 @@ function applyPiSetup(plan) {
           `Pi attempted to downgrade ${pkg.packageName} from ${prior.version} to ${verified.version}; exact-version recovery ${recoverySucceeded ? "verified" : "failed or unverifiable"}. ${recoveryGuidance}`
         );
       }
-      if (verified.state !== "installed")
-        throw new Error(`Pi did not verify ${pkg.source}: ${verified.reason}.`);
+      if (verified.state !== "installed") {
+        manualRecovery = piPreservedPackageRecovery(pkg, verified);
+        throw new Error(
+          `Pi did not verify ${pkg.source}: ${verified.reason}.${manualRecovery ? ` ${manualRecovery}` : ""}`
+        );
+      }
+      if (preserving) {
+        if (verified.source !== prior.source || !piPackagePathsEqual(verified.installedPath, prior.installedPath))
+          throw new Error(
+            `Preserved Pi package ${pkg.packageName} changed source or directory during verification; inspect pi list --no-approve, then rerun setup.`
+          );
+        diagnostics.push(
+          `Preserved and verified ${pkg.packageName}@${verified.version} from ${verified.source}; no reinstall.`
+        );
+      }
       installedPackages.push(pkg.source);
     }
     for (const item of plan.items.filter(
@@ -9422,6 +9567,18 @@ function statusFromPlan(plan, context2, evidence = {}) {
     ...plan.projectIncumbentTodos ?? []
   ];
   const packageSpecs = getPiExternalPackageSpecs(plan.options);
+  let preservationPackages = configuredPackages;
+  let preservationError;
+  if (packages.exitCode === 0) {
+    try {
+      preservationPackages = resolvePiPreservationPackages(packages.stdout, {
+        ...plan.options,
+        commandExecutor: execute
+      });
+    } catch (error) {
+      preservationError = error instanceof Error ? error.message : String(error);
+    }
+  }
   for (const target of targets.filter(
     (candidate) => candidate.kind === "package" && packageSpecs.some(({ source }) => source === candidate.path)
   )) {
@@ -9432,8 +9589,14 @@ function statusFromPlan(plan, context2, evidence = {}) {
       target.state = "unknown";
       target.observed = packages.stderr.trim() || "pi list unavailable";
     } else if (externalSpec) {
-      const inspected = inspectPiExternalPackage(
-        configuredPackages,
+      const preserveUserCopy = externalSpec.preserveUserCopy === true;
+      if (preserveUserCopy && preservationError) {
+        target.state = "drift";
+        target.observed = preservationError;
+        continue;
+      }
+      const inspected = inspectPiSetupPackage(
+        preserveUserCopy ? preservationPackages : configuredPackages,
         externalSpec,
         externalSpec.id !== "delegation" || plan.options.runtimePackageRoot !== void 0
       );