@bigking67/pi-67 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.10.2]
+
+- Reads `Manager latest` through the npm registry HTTP API instead of spawning
+  local `npm` / `npm.cmd`, fixing Windows environments where command shims fail
+  with `spawnSync npm.cmd EINVAL`.
+- Adds a final Windows `cmd.exe /d /s /c npm.cmd ...` fallback for explicit npm
+  operations such as `pi-67 self-update`.
+- Adds read-only visibility for legacy PowerShell
+  `~/.pi/agent-backups/pre-update-*` conflict snapshots through
+  `pi-67 backups list --include-legacy` and
+  `pi-67 backups inspect --legacy <pre-update-id>`.
+
 ## [0.10.1]
 
 - Falls back from `npm` to `npm.cmd` on Windows when checking npm registry state

package/README.md

@@ -39,7 +39,10 @@ pi-67 update --repair
 ```
 
 `pi-67 update --check` reports whether the npm manager is outdated. Updating the
-manager itself is explicit:
+manager itself is explicit. The latest-version check reads the npm registry
+HTTP API directly and does not depend on spawning local `npm` / `npm.cmd`.
+Explicit npm operations such as `self-update` still use npm, with Windows
+fallback through `cmd.exe /d /s /c npm.cmd ...`:
 
 ```bash
 pi-67 self-update
@@ -80,7 +83,9 @@ Runtime backups are first-class CLI state:
 
 ```bash
 pi-67 backups list
+pi-67 backups list --include-legacy
 pi-67 backups inspect <backup-id-or-path>
+pi-67 backups inspect <pre-update-id> --legacy
 pi-67 backups restore --from <backup-id-or-path> --dry-run
 pi-67 backups restore --from <backup-id-or-path> --yes
 ```
@@ -88,6 +93,11 @@ pi-67 backups restore --from <backup-id-or-path> --yes
 The restore command only restores preserved runtime files and writes a
 pre-restore backup before overwriting current local config.
 
+Legacy PowerShell `~/.pi/agent-backups/pre-update-*` directories are read-only
+known-conflict snapshots from older migration paths. They are listed only with
+`--include-legacy` and are intentionally separate from restorable runtime
+backups under `~/.pi/pi67/backups/`.
+
 Theme changes are explicit only:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigking67/pi-67",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Cross-platform manager CLI for the pi-67 Pi Coding Agent distribution.",
   "type": "module",
   "bin": {

package/scripts/check.mjs

@@ -3,13 +3,15 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { npmPublishTargetStatus } from "../src/lib/npm-registry.mjs";
+import { npmLatestVersion, npmPublishTargetStatus, npmRegistryPackageUrl } from "../src/lib/npm-registry.mjs";
 import { commandCandidatesForPlatform } from "../src/lib/shell-runner.mjs";
 import { readExtensionRegistry, validateExtensionRegistry } from "../src/lib/extension-registry.mjs";
 import { buildPlanDecisions, classifyGitShort } from "../src/lib/update-plan.mjs";
 import {
   beginUpdateLifecycle,
+  inspectLegacyConflictBackup,
   inspectRuntimeBackup,
+  listLegacyConflictBackups,
   listRuntimeBackups,
   restoreRuntimeBackup,
 } from "../src/lib/update-safety.mjs";
@@ -26,6 +28,7 @@ for (const file of files.filter((item) => item.endsWith(".mjs"))) {
 for (const file of files.filter((item) => item.endsWith(".json"))) {
   JSON.parse(fs.readFileSync(file, "utf8"));
 }
+await runNpmRegistrySelfTests();
 runPublishTargetSelfTests();
 runShellRunnerSelfTests();
 runExtensionRegistrySelfTests();
@@ -94,10 +97,53 @@ function runPublishTargetSelfTests() {
   );
 }
 
+async function runNpmRegistrySelfTests() {
+  assert(
+    npmRegistryPackageUrl("@bigking67/pi-67") === "https://registry.npmjs.org/@bigking67%2Fpi-67/latest",
+    "scoped npm package registry URL must use the direct registry endpoint",
+  );
+  const current = await npmLatestVersion("@example/pkg", {
+    currentVersion: "0.9.0",
+    fetchImpl: async () => jsonResponse(200, { version: "1.2.3" }),
+  });
+  assert(current.ok && current.latestVersion === "1.2.3" && current.outdated, "direct registry latest lookup must parse version payloads");
+
+  const missing = await npmLatestVersion("@example/missing", {
+    fetchImpl: async () => jsonResponse(404, { error: "not found" }),
+  });
+  assert(missing.message === "not published on npm registry yet", "direct registry 404 must classify unpublished packages");
+
+  const malformed = await npmLatestVersion("@example/bad", {
+    fetchImpl: async () => jsonResponse(200, { name: "@example/bad" }),
+  });
+  assert(!malformed.ok && malformed.message === "npm registry returned no version", "direct registry malformed payloads must fail closed");
+
+  const invalidJson = await npmLatestVersion("@example/invalid-json", {
+    fetchImpl: async () => ({
+      ok: true,
+      status: 200,
+      statusText: "OK",
+      async json() {
+        throw new SyntaxError("Unexpected token");
+      },
+    }),
+  });
+  assert(invalidJson.message === "npm registry returned invalid JSON", "direct registry invalid JSON must be classified");
+
+  const timeout = await npmLatestVersion("@example/slow", {
+    fetchImpl: async () => {
+      const error = new Error("The operation was aborted");
+      error.name = "AbortError";
+      throw error;
+    },
+  });
+  assert(timeout.message === "npm registry lookup timed out", "direct registry aborts must classify as timeouts");
+}
+
 function runShellRunnerSelfTests() {
   assert(
-    JSON.stringify(commandCandidatesForPlatform("npm", "win32")) === JSON.stringify(["npm", "npm.cmd"]),
-    "Windows npm execution must fall back to npm.cmd",
+    JSON.stringify(commandCandidatesForPlatform("npm", "win32")) === JSON.stringify(["npm", "npm.cmd", "cmd.exe"]),
+    "Windows npm execution must fall back through npm.cmd and cmd.exe",
   );
   assert(
     JSON.stringify(commandCandidatesForPlatform("git", "win32")) === JSON.stringify(["git"]),
@@ -348,6 +394,18 @@ function runUpdateSafetySelfTests() {
     fs.readFileSync(path.join(agentDir, "settings.json"), "utf8").includes("\"dark\""),
     "runtime backup restore must recover the backed up file content",
   );
+  const legacyRoot = path.join(path.dirname(stateDir), "agent-backups", "pre-update-20260707-235901");
+  fs.mkdirSync(legacyRoot, { recursive: true });
+  fs.writeFileSync(path.join(legacyRoot, "local.diff"), "diff --git a/settings.json b/settings.json\n");
+  fs.writeFileSync(path.join(legacyRoot, "settings.json"), "{\"theme\":\"legacy\"}\n");
+  assert(
+    listLegacyConflictBackups(ctx).some((item) => item.id === "pre-update-20260707-235901" && item.hasLocalDiff),
+    "legacy PowerShell conflict backups must be listable",
+  );
+  assert(
+    inspectLegacyConflictBackup(ctx, "pre-update-20260707-235901").files.some((item) => item.name === "local.diff"),
+    "legacy PowerShell conflict backups must be inspectable",
+  );
   fs.rmSync(tmpRoot, { recursive: true, force: true });
 }
 
@@ -413,6 +471,17 @@ function deepMerge(base, overrides) {
   return next;
 }
 
+function jsonResponse(status, payload) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 404 ? "Not Found" : "OK",
+    async json() {
+      return payload;
+    },
+  };
+}
+
 function assert(condition, message) {
   if (!condition) throw new Error(message);
 }

package/src/commands/backups.mjs

@@ -1,6 +1,9 @@
+import path from "node:path";
 import { parseCommandOptions } from "../lib/args.mjs";
 import {
+  inspectLegacyConflictBackup,
   inspectRuntimeBackup,
+  listLegacyConflictBackups,
   listRuntimeBackups,
   restoreRuntimeBackup,
 } from "../lib/update-safety.mjs";
@@ -20,14 +23,16 @@ export async function backupsCommand(ctx, argv) {
 
 function listCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
-    bools: ["json"],
+    bools: ["json", "include-legacy"],
   });
   const backups = listRuntimeBackups(ctx);
+  const legacyConflictBackups = listLegacyConflictBackups(ctx);
   if (ctx.json || options.json) {
     printJson({
       schema: "pi67.backups-list.v1",
       createdAt: new Date().toISOString(),
       backups,
+      legacyConflictBackups: options.includeLegacy ? legacyConflictBackups : undefined,
     });
     return;
   }
@@ -35,21 +40,32 @@ function listCommand(ctx, argv) {
   keyValue("Backups dir", `${ctx.stateDir}/backups`);
   if (backups.length === 0) {
     warn("no runtime backups found");
-    return;
+  } else {
+    for (const item of backups) {
+      info(`${item.id}: ${item.operation}; files=${item.fileCount}; created=${item.createdAt || "unknown"}`);
+    }
   }
-  for (const item of backups) {
-    info(`${item.id}: ${item.operation}; files=${item.fileCount}; created=${item.createdAt || "unknown"}`);
+  if (legacyConflictBackups.length > 0) {
+    section("Legacy conflict backups");
+    keyValue("Backups dir", path.join(path.dirname(ctx.stateDir), "agent-backups"));
+    if (!options.includeLegacy) {
+      warn(`${legacyConflictBackups.length} legacy pre-update conflict backups found; rerun with --include-legacy to list them.`);
+    } else {
+      for (const item of legacyConflictBackups) {
+        info(`${item.id}: ${item.operation}; files=${item.fileCount}; bytes=${item.totalBytes}; created=${item.createdAt || "unknown"}`);
+      }
+    }
   }
 }
 
 function inspectCommand(ctx, argv) {
   const { options, positionals } = parseCommandOptions(argv, {
-    bools: ["json"],
+    bools: ["json", "legacy"],
   });
-  const backup = inspectRuntimeBackup(ctx, positionals[0]);
+  const backup = options.legacy ? inspectLegacyConflictBackup(ctx, positionals[0]) : inspectRuntimeBackup(ctx, positionals[0]);
   if (ctx.json || options.json) {
     printJson({
-      schema: "pi67.backup-inspect.v1",
+      schema: options.legacy ? "pi67.legacy-conflict-backup-inspect.v1" : "pi67.backup-inspect.v1",
       createdAt: new Date().toISOString(),
       backup,
     });
@@ -60,8 +76,13 @@ function inspectCommand(ctx, argv) {
   keyValue("Path", backup.path);
   keyValue("Created", backup.createdAt || "unknown");
   keyValue("Operation", backup.operation);
+  if (backup.reason) keyValue("Reason", backup.reason);
   keyValue("Files", `${backup.fileCount}${backup.preservedCount === undefined ? "" : ` present / ${backup.preservedCount} preserved slots`}`);
   for (const file of backup.files) {
+    if (file.name) {
+      info(`${file.name}${file.bytes === undefined ? "" : ` bytes=${file.bytes}`}`);
+      continue;
+    }
     if (file.exists === false) {
       info(`${file.path} missing-at-backup-time`);
     } else {
@@ -111,13 +132,15 @@ function printBackupsHelp() {
   process.stdout.write(`pi-67 backups - inspect and restore preserved runtime backups
 
 Usage:
-  pi-67 backups list [--json]
-  pi-67 backups inspect <backup-id-or-path> [--json]
+  pi-67 backups list [--include-legacy] [--json]
+  pi-67 backups inspect <backup-id-or-path> [--legacy] [--json]
   pi-67 backups restore --from <backup-id-or-path> [--dry-run] [--yes] [--json]
 
 Examples:
   pi-67 backups list
+  pi-67 backups list --include-legacy
   pi-67 backups inspect 20260707T120000Z-update
+  pi-67 backups inspect pre-update-20260707-235901 --legacy
   pi-67 backups restore --from 20260707T120000Z-update --dry-run
   pi-67 backups restore --from 20260707T120000Z-update --yes
 `);

package/src/commands/extensions.mjs

@@ -37,7 +37,7 @@ function list(ctx, argv) {
   }
 }
 
-function doctor(ctx, argv) {
+async function doctor(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "strict-shared-skills", "no-remote"],
   });
@@ -46,7 +46,7 @@ function doctor(ctx, argv) {
     manifest,
     requiredIds: REQUIRED_EXTENSION_REGISTRY_IDS,
   });
-  const updatePlan = buildUpdatePlan(ctx, {
+  const updatePlan = await buildUpdatePlan(ctx, {
     noRemote: ctx.noRemote || options.noRemote,
     strictSharedSkills: options.strictSharedSkills,
   });
@@ -120,11 +120,11 @@ function inspect(ctx, argv) {
   for (const smoke of entry.smoke) info(smoke);
 }
 
-function plan(ctx, argv) {
+async function plan(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "strict-shared-skills", "no-remote"],
   });
-  const updatePlan = buildUpdatePlan(ctx, {
+  const updatePlan = await buildUpdatePlan(ctx, {
     noRemote: ctx.noRemote || options.noRemote,
     strictSharedSkills: options.strictSharedSkills,
   });

package/src/commands/publish-check.mjs

@@ -18,7 +18,7 @@ export async function publishCheckCommand(ctx, argv) {
   const noRemote = ctx.noRemote || options.noRemote;
   const noPack = options.noPack;
   const strict = options.strict;
-  const report = buildPublishCheck(ctx, {
+  const report = await buildPublishCheck(ctx, {
     noRemote,
     noPack,
     allowFirstPublish: options.allowFirstPublish,
@@ -35,14 +35,14 @@ export async function publishCheckCommand(ctx, argv) {
   }
 }
 
-function buildPublishCheck(ctx, options) {
+async function buildPublishCheck(ctx, options) {
   const pkg = readCliPackageJson();
   const rootPackage = readJsonIfExists(path.join(ctx.repoRoot, "package.json")) || {};
   const versionFile = readTextIfExists(path.join(ctx.repoRoot, "VERSION")).trim();
   const workflowFile = path.join(ctx.repoRoot, ".github", "workflows", "npm-publish.yml");
   const workflow = workflowCheck(workflowFile);
   const git = fs.existsSync(ctx.repoRoot) ? gitStatus(ctx.repoRoot) : { isRepo: false };
-  const registry = npmLatestVersion(pkg.name, {
+  const registry = await npmLatestVersion(pkg.name, {
     currentVersion: pkg.version,
     noRemote: options.noRemote,
     timeoutMs: 10000,

package/src/commands/status.mjs

@@ -6,7 +6,7 @@ export async function statusCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "no-remote"],
   });
-  const plan = buildUpdatePlan(ctx, { noRemote: ctx.noRemote || options.noRemote });
+  const plan = await buildUpdatePlan(ctx, { noRemote: ctx.noRemote || options.noRemote });
   if (ctx.json || options.json) {
     printJson(plan);
     return;

package/src/commands/update.mjs

@@ -27,7 +27,7 @@ export async function updateCommand(ctx, argv) {
   const dryRun = ctx.dryRun || options.dryRun;
   const json = ctx.json || options.json;
   if (options.check) {
-    const plan = buildUpdatePlan(ctx, {
+    const plan = await buildUpdatePlan(ctx, {
       noRemote: ctx.noRemote || options.noRemote,
       strictSharedSkills: options.strictSharedSkills,
     });
@@ -39,7 +39,7 @@ export async function updateCommand(ctx, argv) {
     return;
   }
 
-  const plan = buildUpdatePlan(ctx, {
+  const plan = await buildUpdatePlan(ctx, {
     noRemote: ctx.noRemote || options.noRemote,
     strictSharedSkills: options.strictSharedSkills,
   });

package/src/lib/npm-registry.mjs

@@ -1,23 +1,22 @@
 import { captureCommand } from "./shell-runner.mjs";
 
-export function npmLatestVersion(packageName, options = {}) {
+const DEFAULT_REGISTRY_BASE_URL = "https://registry.npmjs.org";
+
+export async function npmLatestVersion(packageName, options = {}) {
   if (options.noRemote) {
     return { skipped: true, ok: false, latestVersion: "", outdated: false, message: "remote checks skipped" };
   }
-  const result = captureCommand("npm", ["view", packageName, "version", "--json"], {
-    timeoutMs: options.timeoutMs || 8000,
-  });
+  const result = await npmRegistryLatestPayload(packageName, options);
   if (!result.ok) {
-    const rawMessage = result.stderr || result.error || "npm registry lookup failed";
     return {
       skipped: false,
       ok: false,
       latestVersion: "",
       outdated: false,
-      message: rawMessage.includes("E404") ? "not published on npm registry yet" : compactMessage(rawMessage),
+      message: result.message,
     };
   }
-  const latestVersion = parseNpmVersion(result.stdout);
+  const latestVersion = parseNpmLatestPayload(result.payload);
   return {
     skipped: false,
     ok: Boolean(latestVersion),
@@ -27,6 +26,55 @@ export function npmLatestVersion(packageName, options = {}) {
   };
 }
 
+export function npmRegistryPackageUrl(packageName, options = {}) {
+  const baseUrl = String(options.registryBaseUrl || DEFAULT_REGISTRY_BASE_URL).replace(/\/+$/, "");
+  const encodedPackage = encodeURIComponent(String(packageName || "")).replace(/^%40/, "@");
+  return `${baseUrl}/${encodedPackage}/latest`;
+}
+
+async function npmRegistryLatestPayload(packageName, options = {}) {
+  const timeoutMs = options.timeoutMs || 8000;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    clearTimeout(timeout);
+    return {
+      ok: false,
+      message: "npm registry lookup failed: fetch unavailable in this Node runtime",
+    };
+  }
+  try {
+    const response = await fetchImpl(npmRegistryPackageUrl(packageName, options), {
+      signal: controller.signal,
+      headers: {
+        accept: "application/json",
+        "user-agent": "pi-67-manager",
+      },
+    });
+    if (!response.ok) {
+      return {
+        ok: false,
+        message: response.status === 404
+          ? "not published on npm registry yet"
+          : `npm registry lookup failed: HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`,
+      };
+    }
+    try {
+      return { ok: true, payload: await response.json() };
+    } catch {
+      return { ok: false, message: "npm registry returned invalid JSON" };
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      message: registryErrorMessage(error),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 export function npmPackageScopeStatus(packageName, options = {}) {
   const scope = packageScope(packageName);
   if (!scope) {
@@ -228,15 +276,14 @@ function packageScope(packageName) {
   return match ? match[1] : "";
 }
 
-function parseNpmVersion(value) {
-  const trimmed = String(value || "").trim();
-  if (!trimmed) return "";
-  try {
-    const parsed = JSON.parse(trimmed);
-    return typeof parsed === "string" ? parsed : "";
-  } catch {
-    return trimmed.replace(/^"|"$/g, "");
-  }
+function parseNpmLatestPayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return "";
+  return typeof payload.version === "string" ? payload.version.trim() : "";
+}
+
+function registryErrorMessage(error) {
+  if (error?.name === "AbortError") return "npm registry lookup timed out";
+  return `npm registry lookup failed: ${compactMessage(error?.message || error || "unknown error")}`;
 }
 
 function parseJsonObject(value) {

package/src/lib/shell-runner.mjs

@@ -41,21 +41,34 @@ export function captureCommand(command, args = [], options = {}) {
 
 export function commandCandidatesForPlatform(command, platform = process.platform) {
   if (platform === "win32" && command === "npm") {
-    return ["npm", "npm.cmd"];
+    return ["npm", "npm.cmd", "cmd.exe"];
   }
   return [command];
 }
 
 function spawnWithFallback(command, args, options) {
   let lastResult;
-  for (const candidate of commandCandidatesForPlatform(command)) {
-    const result = spawnSync(candidate, args, options);
+  for (const candidate of commandInvocationsForPlatform(command, args)) {
+    const result = spawnSync(candidate.command, candidate.args, options);
     lastResult = result;
-    if (!isCommandNotFound(result)) return { command: candidate, result };
+    if (!isRetryableSpawnFailure(command, result)) return { command: candidate.command, result };
   }
   return { command, result: lastResult };
 }
 
-function isCommandNotFound(result) {
-  return result?.error?.code === "ENOENT";
+function commandInvocationsForPlatform(command, args, platform = process.platform) {
+  if (platform === "win32" && command === "npm") {
+    return [
+      { command: "npm", args },
+      { command: "npm.cmd", args },
+      { command: process.env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", "npm.cmd", ...args] },
+    ];
+  }
+  return [{ command, args }];
+}
+
+function isRetryableSpawnFailure(command, result, platform = process.platform) {
+  if (result?.error?.code === "ENOENT") return true;
+  if (platform === "win32" && command === "npm" && result?.error?.code === "EINVAL") return true;
+  return false;
 }

package/src/lib/update-plan.mjs

@@ -10,7 +10,7 @@ import { npmLatestVersion } from "./npm-registry.mjs";
 import { buildDistroManifest } from "./distro-manifest.mjs";
 import { PRESERVED_RUNTIME_FILES } from "./update-safety.mjs";
 
-export function buildUpdatePlan(ctx, options = {}) {
+export async function buildUpdatePlan(ctx, options = {}) {
   const versionFile = path.join(ctx.repoRoot, "VERSION");
   const settings = readJsonFileIfExists(path.join(ctx.agentDir, "settings.json")) || {};
   const theme = currentTheme(ctx);
@@ -35,7 +35,7 @@ export function buildUpdatePlan(ctx, options = {}) {
     fs.existsSync(path.join(ctx.repoRoot, "scripts", name)),
   ]));
   const pkg = readCliPackageJson();
-  const managerRegistry = npmLatestVersion(pkg.name, {
+  const managerRegistry = await npmLatestVersion(pkg.name, {
     currentVersion: pkg.version,
     noRemote: options.noRemote,
   });

package/src/lib/update-safety.mjs

@@ -116,6 +116,16 @@ export function listRuntimeBackups(ctx) {
     .sort((left, right) => String(right.createdAt || right.id).localeCompare(String(left.createdAt || left.id)));
 }
 
+export function listLegacyConflictBackups(ctx) {
+  const root = legacyConflictBackupsDir(ctx);
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith("pre-update-"))
+    .map((entry) => legacyConflictBackupSummary(path.join(root, entry.name)))
+    .filter(Boolean)
+    .sort((left, right) => String(right.createdAt || right.id).localeCompare(String(left.createdAt || left.id)));
+}
+
 export function inspectRuntimeBackup(ctx, input) {
   const backupDir = resolveBackupDir(ctx, input);
   const summary = backupSummary(backupDir);
@@ -125,6 +135,15 @@ export function inspectRuntimeBackup(ctx, input) {
   return summary;
 }
 
+export function inspectLegacyConflictBackup(ctx, input) {
+  const backupDir = resolveLegacyConflictBackupDir(ctx, input);
+  const summary = legacyConflictBackupSummary(backupDir, { includeFiles: true });
+  if (!summary) {
+    throw new CliError(`legacy conflict backup not found or unreadable: ${backupDir}`);
+  }
+  return summary;
+}
+
 export function restoreRuntimeBackup(ctx, input, options = {}) {
   const backup = inspectRuntimeBackup(ctx, input);
   const dryRun = Boolean(options.dryRun);
@@ -267,6 +286,46 @@ function backupSummary(backupDir) {
   }
 }
 
+function legacyConflictBackupsDir(ctx) {
+  return path.join(path.dirname(ctx.stateDir), "agent-backups");
+}
+
+function legacyConflictBackupSummary(backupDir, options = {}) {
+  try {
+    if (!fs.existsSync(backupDir) || !fs.statSync(backupDir).isDirectory()) return null;
+    const entries = fs.readdirSync(backupDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => {
+        const file = path.join(backupDir, entry.name);
+        const stat = fs.statSync(file);
+        return {
+          name: entry.name,
+          path: file,
+          bytes: stat.size,
+          mtime: stat.mtime.toISOString(),
+        };
+      });
+    const stat = fs.statSync(backupDir);
+    const totalBytes = entries.reduce((sum, item) => sum + item.bytes, 0);
+    const localDiff = entries.find((item) => item.name === "local.diff");
+    return {
+      id: path.basename(backupDir),
+      path: backupDir,
+      schema: "pi67.legacy-conflict-backup.v1",
+      createdAt: stat.mtime.toISOString(),
+      operation: "known-migration-conflict",
+      reason: "PowerShell updater preserved known migration conflict files before restoring them from HEAD",
+      fileCount: entries.length,
+      totalBytes,
+      hasLocalDiff: Boolean(localDiff),
+      localDiffPath: localDiff?.path || "",
+      files: options.includeFiles ? entries : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
 function resolveBackupDir(ctx, input) {
   if (!input) throw new CliError("backup id/path is required", 2);
   const expanded = expandHome(String(input));
@@ -276,6 +335,15 @@ function resolveBackupDir(ctx, input) {
   return path.join(ctx.stateDir, "backups", expanded);
 }
 
+function resolveLegacyConflictBackupDir(ctx, input) {
+  if (!input) throw new CliError("legacy backup id/path is required", 2);
+  const expanded = expandHome(String(input));
+  if (path.isAbsolute(expanded) || expanded.includes("/") || expanded.includes("\\")) {
+    return path.resolve(expanded);
+  }
+  return path.join(legacyConflictBackupsDir(ctx), expanded);
+}
+
 function inferBackupOperation(id) {
   if (id.endsWith("-update")) return "update";
   if (id.endsWith("-repair")) return "repair";