@unbrained/pm-cli 2026.7.14 → 2026.7.16

package/dist/cli-bundle/chunks/{chunk-DVOLZJ3C.js → chunk-J6EY5V4N.js}

@@ -1,34 +1,35 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6800d243-3c57-59f4-8e55-c1613574d53e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f34a834c-7c67-555c-a8b0-6c26e7d8c12a")}catch(e){}}();
+import {
+  ensureTypeFolderScaffold
+} from "./chunk-INU6DKT5.js";
 import {
-  EXECUTABLE_COMMAND_ALIASES,
   normalizeExtensionNameForMatch,
   normalizeManagedDirectoryName,
   normalizeStringList,
   parseExtensionManifest,
+  quoteCommandArg,
   renderPmCommand,
   validateExtensionDirectory
-} from "./chunk-DBZVUJTK.js";
+} from "./chunk-H3EIEWGR.js";
 import {
   describeExtensionActivation,
   renderExtensionSurfaceMarkdown
-} from "./chunk-MQZ3PLCF.js";
-import {
-  ensureTypeFolderScaffold
-} from "./chunk-UGTVWL3E.js";
+} from "./chunk-2IFFUZLC.js";
 import {
   TYPE_PRESET_NAMES,
   normalizeTypePresetName,
   resolveTypePresetDefinitions
-} from "./chunk-ABRCOSDC.js";
+} from "./chunk-3WM75PWC.js";
 import {
+  EXECUTABLE_COMMAND_ALIASES,
   PM_CORE_COMMAND_NAMES
-} from "./chunk-N3CMP4NI.js";
+} from "./chunk-3S5QVM5H.js";
 import {
   parseItemTypesFile,
   serializeItemTypesFile,
   upsertItemType
-} from "./chunk-3TL7WOEF.js";
+} from "./chunk-6N2VXVTQ.js";
 import {
   splitCommaList
 } from "./chunk-NETP4DY4.js";
@@ -40,7 +41,7 @@ import {
   readSettings,
   runActiveOnWriteHooks,
   writeSettings
-} from "./chunk-GSEADLRH.js";
+} from "./chunk-Q7A43DS4.js";
 import {
   DEFAULT_RUNTIME_SCHEMA_FILE_PATHS,
   EXIT_CODE,
@@ -53,6 +54,7 @@ import {
   activateExtensions,
   ensureRuntimeSchemaFileScaffold,
   filePathForSchemaSection,
+  getSettingsPath,
   isPathWithinDirectory,
   levenshteinDistanceWithinLimit,
   loadExtensions,
@@ -69,7 +71,7 @@ import {
   resolvePmPackageRootFromModule,
   resolvePmRoot,
   writeFileAtomic
-} from "./chunk-GXXC7QSK.js";
+} from "./chunk-QKECXBBG.js";
 
 // dist/core/packages/manifest.js
 import fs from "node:fs/promises";
@@ -277,7 +279,7 @@ async function collectPackageExtensionDirectories(packageRoot) {
   return [...discovered].sort((left, right) => left.localeCompare(right));
 }
 
-// dist/cli/commands/extension/scaffold.js
+// dist/sdk/extension/scaffold.js
 import fs2 from "node:fs/promises";
 import path2 from "node:path";
 var SCAFFOLD_MANIFEST_VERSION = 1;
@@ -2435,7 +2437,7 @@ async function scaffoldExtensionProject(target, vocabulary = "extension", capabi
   };
 }
 
-// dist/cli/commands/extension/describe.js
+// dist/sdk/extension/describe.js
 function layerNameKey(layer, name) {
   return `${layer}:${normalizeExtensionNameForMatch(name)}`;
 }
@@ -2504,15 +2506,11 @@ function renderExtensionDescribeMarkdown(result, noun) {
 `;
 }
 
-// dist/cli/commands/extension.js
-import { execFile as execFile2 } from "node:child_process";
-import fs6 from "node:fs/promises";
-import os2 from "node:os";
-import path6 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { promisify as promisify2 } from "node:util";
+// dist/sdk/extension.js
+import fs8 from "node:fs/promises";
+import path8 from "node:path";
 
-// dist/cli/commands/extension/managed-state.js
+// dist/sdk/extension/managed-state.js
 import fs3 from "node:fs/promises";
 import path3 from "node:path";
 var MANAGED_EXTENSION_STATE_FILENAME = ".managed-extensions.json";
@@ -2683,7 +2681,7 @@ function upsertManagedEntry(state, entry) {
   };
 }
 
-// dist/cli/commands/extension/install-sources.js
+// dist/sdk/extension/install-sources.js
 import { execFile } from "node:child_process";
 import fs5 from "node:fs/promises";
 import os from "node:os";
@@ -2691,7 +2689,7 @@ import path5 from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
-// dist/cli/commands/extension/bundled-catalog.js
+// dist/sdk/extension/bundled-catalog.js
 import fs4 from "node:fs/promises";
 import path4 from "node:path";
 var PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
@@ -2712,7 +2710,7 @@ function resolvePackageRootCandidates() {
   if (typeof envRoot === "string" && envRoot.trim().length > 0) {
     candidates.push(path4.resolve(envRoot.trim()));
   }
-  candidates.push(resolvePmPackageRootFromModule(import.meta.url, ["../../../.."]));
+  candidates.push(resolvePmPackageRootFromModule(import.meta.url, ["../../.."]));
   return [...new Set(candidates)];
 }
 async function resolveBundledExtensionAliasSource(input3) {
@@ -2940,7 +2938,7 @@ function projectPackageCatalogEntry(entry, fields) {
   return projected;
 }
 
-// dist/cli/commands/extension/install-sources.js
+// dist/sdk/extension/install-sources.js
 var execFileAsync = promisify(execFile);
 var PM_CLI_PACKAGE_NAME = "@unbrained/pm-cli";
 var bundledPackageAliasesCache;
@@ -3041,9 +3039,12 @@ function parseExtensionInstallSource(input3, options = {}) {
     absolute_path: path5.resolve(process.cwd(), normalizedInput)
   };
 }
-async function runGitCommand(args, execRunner = execFileAsync) {
+async function runGitCommand(args, execRunner = execFileAsync, timeoutMs) {
   try {
-    const result = await execRunner("git", args, { encoding: "utf8" });
+    const result = await execRunner("git", args, {
+      encoding: "utf8",
+      timeout: timeoutMs
+    });
     return (result.stdout ?? "").trim();
   } catch (error) {
     const stderr = typeof error === "object" && error !== null && "stderr" in error ? String(error.stderr) : "";
@@ -3360,7 +3361,7 @@ function removeHostedPmCliDependency(manifest) {
 }
 async function linkHostedPmCliDependency(packageRoot) {
   const hostPackageRoot = resolvePmPackageRootFromModule(import.meta.url, [
-    "../../../.."
+    "../../.."
   ]);
   const [scope, packageName] = PM_CLI_PACKAGE_NAME.split("/");
   const scopedDirectory = path5.join(packageRoot, "node_modules", scope);
@@ -3545,7 +3546,7 @@ async function areDirectoriesEquivalent(left, right) {
   return leftRealPath === rightRealPath;
 }
 
-// dist/cli/commands/extension/doctor.js
+// dist/sdk/extension/doctor.js
 function addRuntimePath(pathsByExtension, extensionName, pathValue) {
   const normalizedName = normalizeExtensionNameForMatch(extensionName);
   const normalizedPath = pathValue.trim();
@@ -4055,12 +4056,347 @@ function buildDoctorConsistencySummary(scope, installedExtensions, loadedExtensi
   };
 }
 
-// dist/cli/commands/extension.js
-var execFileAsync2 = promisify2(execFile2);
+// dist/sdk/extension/install-runtime.js
+import { randomUUID } from "node:crypto";
+import fs6 from "node:fs/promises";
+import os2 from "node:os";
+import path6 from "node:path";
 var EXTENSION_INSTALL_COPY_ATTEMPTS = 3;
 var EXTENSION_INSTALL_LOCK_ATTEMPTS = 120;
 var EXTENSION_INSTALL_LOCK_DELAY_MS = 250;
 var EXTENSION_INSTALL_LOCK_STALE_MS = 12e4;
+var RETRIABLE_EXTENSION_INSTALL_COPY_CODES = /* @__PURE__ */ new Set([
+  "EEXIST",
+  "ENOTEMPTY",
+  "ENOENT"
+]);
+var errnoCode = (error) => typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+var isRetriableExtensionInstallCopyError = (error) => RETRIABLE_EXTENSION_INSTALL_COPY_CODES.has(String(errnoCode(error)));
+var isErrnoCode = (error, code) => errnoCode(error) === code;
+var sleep = (ms) => new Promise((resolve) => {
+  setTimeout(resolve, ms);
+});
+var ensureExtensionModuleTypeMarker = async (destinationDirectory) => {
+  const markerPath = path6.join(destinationDirectory, "package.json");
+  if (await pathExists(markerPath)) {
+    return;
+  }
+  await fs6.writeFile(markerPath, `${JSON.stringify({ type: "module" }, null, 2)}
+`, "utf8");
+};
+var resolveCanonicalExtensionInstallDestination = async (destinationDirectory) => {
+  const resolvedDestination = path6.resolve(destinationDirectory);
+  const destinationParent = path6.dirname(resolvedDestination);
+  const destinationRoot = path6.parse(destinationParent).root;
+  let canonicalDestinationParent = await fs6.realpath(destinationRoot).catch(() => destinationRoot);
+  const relativeDestinationParent = path6.relative(destinationRoot, destinationParent);
+  const destinationSegments = relativeDestinationParent === "" ? [] : relativeDestinationParent.split(path6.sep);
+  for (const [index, segment] of destinationSegments.entries()) {
+    const candidate = path6.join(canonicalDestinationParent, segment);
+    try {
+      canonicalDestinationParent = await fs6.realpath(candidate);
+    } catch {
+      canonicalDestinationParent = path6.join(canonicalDestinationParent, ...destinationSegments.slice(index));
+      break;
+    }
+  }
+  return path6.join(canonicalDestinationParent, path6.basename(resolvedDestination));
+};
+var copyExtensionDirectoryWithoutSelfNesting = async (sourceDirectory, destinationDirectory, copyDirectory, temporaryDirectory = os2.tmpdir()) => {
+  const resolvedSource = path6.resolve(sourceDirectory);
+  const canonicalSource = await fs6.realpath(resolvedSource).catch(() => resolvedSource);
+  const canonicalDestination = await resolveCanonicalExtensionInstallDestination(destinationDirectory);
+  if (canonicalSource === canonicalDestination) {
+    return;
+  }
+  if (!isPathWithinDirectory(canonicalSource, canonicalDestination)) {
+    await copyDirectory(sourceDirectory, destinationDirectory, {
+      recursive: true,
+      force: true
+    });
+    return;
+  }
+  const systemTempDirectory = path6.resolve(temporaryDirectory);
+  const stagingBase = isPathWithinDirectory(canonicalSource, systemTempDirectory) ? path6.dirname(canonicalSource) : systemTempDirectory;
+  if (isPathWithinDirectory(canonicalSource, stagingBase)) {
+    throw new PmCliError(`Extension source "${sourceDirectory}" contains its install destination and no external staging directory is available. Install a narrower package directory instead.`, EXIT_CODE.USAGE, { code: "extension_install_source_contains_destination" });
+  }
+  const stagingRoot = await fs6.mkdtemp(path6.join(stagingBase, "pm-extension-copy-"));
+  const stagedDirectory = path6.join(stagingRoot, "extension");
+  try {
+    await copyDirectory(sourceDirectory, stagedDirectory, {
+      recursive: true,
+      force: true
+    });
+    await copyDirectory(stagedDirectory, destinationDirectory, {
+      recursive: true,
+      force: true
+    });
+  } finally {
+    await fs6.rm(stagingRoot, { recursive: true, force: true });
+  }
+};
+var copyExtensionDirectoryForInstall = async (sourceDirectory, destinationDirectory, copyDirectory = fs6.cp) => {
+  for (let attempt = 1; attempt <= EXTENSION_INSTALL_COPY_ATTEMPTS; attempt += 1) {
+    try {
+      await fs6.rm(destinationDirectory, { recursive: true, force: true });
+      await copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory);
+      return;
+    } catch (error) {
+      if (!isRetriableExtensionInstallCopyError(error) || attempt === EXTENSION_INSTALL_COPY_ATTEMPTS) {
+        throw error;
+      }
+      await sleep(EXTENSION_INSTALL_LOCK_DELAY_MS);
+    }
+  }
+};
+var readExtensionInstallLockOwnerToken = async (lockPath) => {
+  let ownerContents;
+  try {
+    ownerContents = await fs6.readFile(path6.join(lockPath, "owner.json"), "utf8");
+  } catch (error) {
+    if (!isErrnoCode(error, "ENOENT"))
+      throw error;
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(ownerContents);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("token" in parsed)) {
+    return null;
+  }
+  const token = parsed.token;
+  return typeof token === "string" && token.length > 0 ? token : null;
+};
+var removeExtensionInstallLockIfOwned = async (lockPath, ownerToken) => {
+  const currentOwnerToken = await readExtensionInstallLockOwnerToken(lockPath);
+  if (currentOwnerToken !== ownerToken) {
+    return false;
+  }
+  await fs6.rm(lockPath, { recursive: true, force: true });
+  return true;
+};
+var reclaimStaleExtensionInstallLock = async (lockPath, staleMs) => {
+  let stat;
+  try {
+    stat = await fs6.stat(lockPath);
+  } catch {
+    return false;
+  }
+  if (Date.now() - stat.mtimeMs <= staleMs) {
+    return false;
+  }
+  const staleOwnerToken = await readExtensionInstallLockOwnerToken(lockPath);
+  if (staleOwnerToken === null) {
+    await fs6.rm(lockPath, { recursive: true, force: true });
+    return true;
+  }
+  return removeExtensionInstallLockIfOwned(lockPath, staleOwnerToken);
+};
+var startExtensionInstallLockHeartbeat = (lockPath, ownerToken, intervalMs) => {
+  let heartbeat = Promise.resolve();
+  const timer = setInterval(() => {
+    heartbeat = heartbeat.then(async () => {
+      if (await readExtensionInstallLockOwnerToken(lockPath) !== ownerToken) {
+        return;
+      }
+      const heartbeatAt = /* @__PURE__ */ new Date();
+      await fs6.utimes(lockPath, heartbeatAt, heartbeatAt);
+    }).catch(() => void 0);
+  }, intervalMs);
+  timer.unref();
+  return async () => {
+    clearInterval(timer);
+    await heartbeat;
+  };
+};
+var createExtensionInstallLock = async (lockPath, owner) => {
+  await fs6.mkdir(lockPath);
+  try {
+    await fs6.writeFile(path6.join(lockPath, "owner.json"), `${JSON.stringify(owner, null, 2)}
+`, "utf8");
+  } catch (error) {
+    await fs6.rm(lockPath, { recursive: true, force: true }).catch(() => {
+    });
+    throw error;
+  }
+};
+var acquireExtensionInstallLock = async (lockPath, owner, attempts, delayMs, staleMs) => {
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      await createExtensionInstallLock(lockPath, owner);
+      return true;
+    } catch (error) {
+      if (!isErrnoCode(error, "EEXIST")) {
+        throw error;
+      }
+      if (await reclaimStaleExtensionInstallLock(lockPath, staleMs)) {
+        attempt -= 1;
+      } else {
+        await sleep(delayMs);
+      }
+    }
+  }
+  return false;
+};
+var withExtensionInstallLock = async (settingsRoot, destinationDirectoryName, run, options) => {
+  const lockRoot = path6.join(settingsRoot, "runtime", "extension-install-locks");
+  const lockPath = path6.join(lockRoot, "scope.lock");
+  await fs6.mkdir(lockRoot, { recursive: true });
+  const { attempts: rawAttempts = EXTENSION_INSTALL_LOCK_ATTEMPTS, delay_ms: rawDelayMs = EXTENSION_INSTALL_LOCK_DELAY_MS, stale_ms: rawStaleMs = EXTENSION_INSTALL_LOCK_STALE_MS, heartbeat_ms: rawHeartbeatMs } = options ?? {};
+  if (![rawAttempts, rawDelayMs, rawStaleMs, rawHeartbeatMs].filter((value) => value !== void 0).every(Number.isFinite)) {
+    throw new PmCliError("Extension install lock timings must be finite numbers.", EXIT_CODE.USAGE);
+  }
+  const attempts = Math.max(1, Math.floor(rawAttempts));
+  const delayMs = Math.max(0, Math.floor(rawDelayMs));
+  const staleMs = Math.floor(rawStaleMs);
+  const heartbeatMs = Math.floor(rawHeartbeatMs ?? staleMs / 3);
+  if (staleMs <= 0 || heartbeatMs <= 0 || heartbeatMs >= staleMs) {
+    throw new PmCliError("Extension install lock timings require stale_ms > 0 and 0 < heartbeat_ms < stale_ms.", EXIT_CODE.USAGE);
+  }
+  const owner = {
+    pid: process.pid,
+    token: randomUUID(),
+    created_at: nowIso(),
+    destination: destinationDirectoryName
+  };
+  const acquired = await acquireExtensionInstallLock(lockPath, owner, attempts, delayMs, staleMs);
+  if (!acquired) {
+    throw new PmCliError(`Timed out waiting for extension install lock for "${destinationDirectoryName}".`, EXIT_CODE.CONFLICT);
+  }
+  const stopHeartbeat = startExtensionInstallLockHeartbeat(lockPath, owner.token, heartbeatMs);
+  try {
+    return await run();
+  } finally {
+    await stopHeartbeat();
+    await removeExtensionInstallLockIfOwned(lockPath, owner.token).catch(() => false);
+  }
+};
+
+// dist/sdk/extension/concurrency.js
+var mapWithFixedConcurrency = async (inputs, concurrency, mapper) => {
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new RangeError("concurrency must be a positive integer");
+  }
+  const results = new Array(inputs.length);
+  let nextIndex = 0;
+  const workers = Array.from({ length: Math.min(concurrency, inputs.length) }, async () => {
+    while (nextIndex < inputs.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await mapper(inputs[index]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+};
+
+// dist/sdk/extension/update-check.js
+var GITHUB_UPDATE_CHECK_TIMEOUT_MS = 1e4;
+var resolveGithubUpdateOutput = (output3, installedCommitInput, checkedAt) => {
+  const references = output3.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => {
+    const [commit, ref = ""] = line.split(/\s+/);
+    return { commit, ref };
+  });
+  const remoteReference = references.find((reference) => reference.ref.endsWith("^{}")) ?? references[0];
+  if (!remoteReference) {
+    return {
+      checked_at: checkedAt,
+      available: null,
+      error: "no_remote_reference_found"
+    };
+  }
+  const installedCommit = installedCommitInput?.trim();
+  return installedCommit ? {
+    checked_at: checkedAt,
+    remote_commit: remoteReference.commit,
+    available: remoteReference.commit !== installedCommit
+  } : {
+    checked_at: checkedAt,
+    remote_commit: remoteReference.commit,
+    available: null,
+    error: "missing_installed_commit"
+  };
+};
+var checkGithubUpdate = async (source, gitCommandRunner = runGitCommand) => {
+  const checkedAt = nowIso();
+  if (source.kind !== "github" || !source.repository) {
+    return {
+      checked_at: checkedAt,
+      available: null,
+      error: "not_a_github_managed_source"
+    };
+  }
+  try {
+    const ref = [source.ref?.trim(), "HEAD"].find(Boolean);
+    const output3 = await gitCommandRunner(["ls-remote", source.repository, ref, `${ref}^{}`], void 0, GITHUB_UPDATE_CHECK_TIMEOUT_MS);
+    return resolveGithubUpdateOutput(output3, source.commit, checkedAt);
+  } catch (error) {
+    return {
+      checked_at: checkedAt,
+      available: null,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+};
+
+// dist/sdk/extension/install-snapshot.js
+import fs7 from "node:fs/promises";
+import path7 from "node:path";
+var readOptionalMetadataFile = async (filePath) => fs7.readFile(filePath).catch((error) => {
+  if (isErrnoCode(error, "ENOENT"))
+    return null;
+  throw error;
+});
+var captureExtensionInstallSnapshot = async (selectedRoot, settingsRoot, destinationDirectory, destinationExists, backupDirectory) => {
+  const managedStatePath = resolveManagedExtensionStatePath(selectedRoot);
+  const settingsPath = getSettingsPath(settingsRoot);
+  const [managedStateContents, settingsContents] = await Promise.all([
+    readOptionalMetadataFile(managedStatePath),
+    readOptionalMetadataFile(settingsPath)
+  ]);
+  if (destinationExists) {
+    await fs7.cp(destinationDirectory, backupDirectory, {
+      recursive: true,
+      force: true
+    });
+  }
+  return {
+    backupDirectory,
+    destinationDirectory,
+    destinationExists,
+    managedStatePath,
+    managedStateContents,
+    settingsPath,
+    settingsContents
+  };
+};
+var restoreExtensionInstallSnapshot = async (snapshot) => {
+  await fs7.rm(snapshot.destinationDirectory, { recursive: true, force: true });
+  if (snapshot.destinationExists) {
+    await fs7.cp(snapshot.backupDirectory, snapshot.destinationDirectory, {
+      recursive: true,
+      force: true
+    });
+  }
+  for (const [filePath, contents] of [
+    [snapshot.managedStatePath, snapshot.managedStateContents],
+    [snapshot.settingsPath, snapshot.settingsContents]
+  ]) {
+    if (contents === null) {
+      await fs7.rm(filePath, { force: true });
+    } else {
+      await fs7.mkdir(path7.dirname(filePath), { recursive: true });
+      await fs7.writeFile(filePath, contents);
+    }
+  }
+};
+
+// dist/sdk/extension.js
+var GITHUB_UPDATE_CHECK_CONCURRENCY = 4;
 var LIFECYCLE_ACTION_TARGETS = [
   ["install", "install", "--install"],
   ["uninstall", "uninstall", "--uninstall"],
@@ -4122,6 +4458,11 @@ var EXTENSION_POLICY_OVERRIDE_LIST_FIELDS = [
   "allowed_services",
   "blocked_services"
 ];
+var EXTENSION_POLICY_OVERRIDE_BOOLEAN_FIELDS = [
+  "disabled",
+  "require_trusted",
+  "require_provenance"
+];
 var DEFAULT_EXTENSION_POLICY_DETAILS = {
   mode: "off",
   trust_mode: "off",
@@ -4142,56 +4483,58 @@ var DEFAULT_EXTENSION_POLICY_DETAILS = {
   blocked_services: [],
   extension_overrides: []
 };
-function normalizePolicyRootLists(policy) {
+var normalizePolicyRootLists = (policy) => {
   const safePolicy = policy ?? DEFAULT_EXTENSION_POLICY_DETAILS;
   const lists = {};
   for (const field of EXTENSION_POLICY_ROOT_LIST_FIELDS) {
     lists[field] = normalizeStringList(safePolicy[field] ?? []);
   }
   return lists;
-}
-function appendNonEmptyPolicyLists(target, lists) {
+};
+var appendNonEmptyPolicyLists = (target, lists) => {
   for (const field of EXTENSION_POLICY_OVERRIDE_LIST_FIELDS) {
     if (lists[field].length > 0) {
       target[field] = lists[field];
     }
   }
   return target;
-}
-function buildExtensionPolicyOverrideDetails(override) {
-  const name = typeof override.name === "string" ? override.name.trim() : "";
-  if (name.length === 0) {
-    return null;
-  }
-  const details = { name };
-  if (override.disabled === true) {
-    details.disabled = true;
-  }
-  if (override.require_trusted === true) {
-    details.require_trusted = true;
-  }
-  if (override.require_provenance === true) {
-    details.require_provenance = true;
+};
+var appendEnabledPolicyScalars = (target, override) => {
+  for (const field of EXTENSION_POLICY_OVERRIDE_BOOLEAN_FIELDS) {
+    if (override[field] === true) {
+      target[field] = true;
+    }
   }
   if (override.sandbox_profile) {
-    details.sandbox_profile = override.sandbox_profile;
+    target.sandbox_profile = override.sandbox_profile;
   }
+  return target;
+};
+var normalizePolicyOverrideLists = (override) => {
   const lists = {};
   for (const field of EXTENSION_POLICY_OVERRIDE_LIST_FIELDS) {
     lists[field] = normalizeStringList(override[field] ?? []);
   }
-  return appendNonEmptyPolicyLists(details, lists);
-}
-function buildExtensionPolicyDetails(policy) {
-  const safePolicy = policy ?? DEFAULT_EXTENSION_POLICY_DETAILS;
+  return lists;
+};
+var buildExtensionPolicyOverrideDetails = (override) => {
+  const name = typeof override.name === "string" ? override.name.trim() : "";
+  if (name.length === 0) {
+    return null;
+  }
+  return appendNonEmptyPolicyLists(appendEnabledPolicyScalars({ name }, override), normalizePolicyOverrideLists(override));
+};
+var normalizeExtensionPolicyOverrides = (overrides) => (overrides ?? []).map((override) => buildExtensionPolicyOverrideDetails(override)).filter((override) => override !== null).sort((left, right) => left.name.localeCompare(right.name));
+var buildExtensionPolicyDetails = (policy) => {
+  const safePolicy = Object.assign({}, DEFAULT_EXTENSION_POLICY_DETAILS, policy ?? {});
   const rootLists = normalizePolicyRootLists(policy);
-  const overrides = (safePolicy.extension_overrides ?? []).map((override) => buildExtensionPolicyOverrideDetails(override)).filter((override) => override !== null).sort((left, right) => left.name.localeCompare(right.name));
+  const overrides = normalizeExtensionPolicyOverrides(safePolicy.extension_overrides);
   return {
-    mode: safePolicy.mode ?? DEFAULT_EXTENSION_POLICY_DETAILS.mode,
-    trust_mode: safePolicy.trust_mode ?? DEFAULT_EXTENSION_POLICY_DETAILS.trust_mode,
+    mode: safePolicy.mode,
+    trust_mode: safePolicy.trust_mode,
     require_provenance: safePolicy.require_provenance === true,
     trusted_extensions: rootLists.trusted_extensions,
-    default_sandbox_profile: safePolicy.default_sandbox_profile ?? "none",
+    default_sandbox_profile: safePolicy.default_sandbox_profile,
     allowed_extensions: rootLists.allowed_extensions,
     blocked_extensions: rootLists.blocked_extensions,
     allowed_capabilities: rootLists.allowed_capabilities,
@@ -4206,149 +4549,41 @@ function buildExtensionPolicyDetails(policy) {
     blocked_services: rootLists.blocked_services,
     extension_overrides: overrides
   };
-}
-function isRetriableExtensionInstallCopyError(error) {
-  if (typeof error !== "object" || error === null || !("code" in error)) {
-    return false;
-  }
-  const code = error.code;
-  return code === "EEXIST" || code === "ENOTEMPTY" || code === "ENOENT";
-}
-function isErrnoCode(error, code) {
-  return typeof error === "object" && error !== null && "code" in error && error.code === code;
-}
-function sleep(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-async function ensureExtensionModuleTypeMarker(destinationDirectory) {
-  const markerPath = path6.join(destinationDirectory, "package.json");
-  if (await pathExists(markerPath)) {
-    return;
+};
+var resolveInstalledExtensionCandidate = async (installed, extensionTarget) => {
+  const lookupValues = [extensionTarget];
+  const bundledAliasManifestName = await resolveBundledAliasManifestName(extensionTarget);
+  if (bundledAliasManifestName) {
+    lookupValues.push(bundledAliasManifestName);
   }
-  await fs6.writeFile(markerPath, `${JSON.stringify({ type: "module" }, null, 2)}
-`, "utf8");
-}
-async function copyExtensionDirectoryForInstall(sourceDirectory, destinationDirectory, copyDirectory = fs6.cp) {
-  for (let attempt = 1; attempt <= EXTENSION_INSTALL_COPY_ATTEMPTS; attempt += 1) {
-    try {
-      if (await pathExists(destinationDirectory)) {
-        await fs6.rm(destinationDirectory, { recursive: true, force: true });
-      }
-      await copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory);
-      return;
-    } catch (error) {
-      if (!isRetriableExtensionInstallCopyError(error) || attempt === EXTENSION_INSTALL_COPY_ATTEMPTS) {
-        throw error;
-      }
-      await sleep(EXTENSION_INSTALL_LOCK_DELAY_MS);
+  const normalizedLookups = [
+    ...new Set(lookupValues.map((value) => normalizeExtensionNameForMatch(value)).filter((value) => value.length > 0))
+  ];
+  for (const lookup of normalizedLookups) {
+    const byName = installed.find((entry) => normalizeExtensionNameForMatch(entry.name) === lookup);
+    if (byName) {
+      return byName;
+    }
+    const byDirectory = installed.find((entry) => normalizeExtensionNameForMatch(entry.directory) === lookup);
+    if (byDirectory) {
+      return byDirectory;
     }
   }
-}
-async function copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory) {
-  const resolvedSource = path6.resolve(sourceDirectory);
-  const resolvedDestination = path6.resolve(destinationDirectory);
-  if (resolvedSource === resolvedDestination) {
-    return;
-  }
-  if (!isPathWithinDirectory(resolvedSource, resolvedDestination)) {
-    await copyDirectory(sourceDirectory, destinationDirectory, {
-      recursive: true,
-      force: true
-    });
-    return;
-  }
-  const stagingRoot = await fs6.mkdtemp(path6.join(os2.tmpdir(), "pm-extension-copy-"));
-  const stagedDirectory = path6.join(stagingRoot, "extension");
-  try {
-    await copyDirectory(sourceDirectory, stagedDirectory, {
-      recursive: true,
-      force: true
-    });
-    await copyDirectory(stagedDirectory, destinationDirectory, {
-      recursive: true,
-      force: true
-    });
-  } finally {
-    await fs6.rm(stagingRoot, { recursive: true, force: true });
-  }
-}
-async function withExtensionInstallLock(settingsRoot, destinationDirectoryName, run, options) {
-  const lockRoot = path6.join(settingsRoot, "runtime", "extension-install-locks");
-  const lockPath = path6.join(lockRoot, `${destinationDirectoryName}.lock`);
-  await fs6.mkdir(lockRoot, { recursive: true });
-  const attempts = Math.max(1, Math.floor(options?.attempts ?? EXTENSION_INSTALL_LOCK_ATTEMPTS));
-  const delayMs = Math.max(0, Math.floor(options?.delay_ms ?? EXTENSION_INSTALL_LOCK_DELAY_MS));
-  const staleMs = Math.max(0, Math.floor(options?.stale_ms ?? EXTENSION_INSTALL_LOCK_STALE_MS));
-  let acquired = false;
-  for (let attempt = 1; attempt <= attempts; attempt += 1) {
-    try {
-      await fs6.mkdir(lockPath);
-      acquired = true;
-      await fs6.writeFile(path6.join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: nowIso(), destination: destinationDirectoryName }, null, 2)}
-`, "utf8");
-      break;
-    } catch (error) {
-      if (!isErrnoCode(error, "EEXIST")) {
-        throw error;
-      }
-      let stat = null;
-      try {
-        stat = await fs6.stat(lockPath);
-      } catch {
-        stat = null;
-      }
-      if (stat && Date.now() - stat.mtimeMs > staleMs) {
-        await fs6.rm(lockPath, { recursive: true, force: true });
-        continue;
-      }
-      await sleep(delayMs);
-    }
-  }
-  if (!acquired) {
-    throw new PmCliError(`Timed out waiting for extension install lock for "${destinationDirectoryName}".`, EXIT_CODE.CONFLICT);
-  }
-  try {
-    return await run();
-  } finally {
-    await fs6.rm(lockPath, { recursive: true, force: true }).catch(() => void 0);
-  }
-}
-async function resolveInstalledExtensionCandidate(installed, extensionTarget) {
-  const lookupValues = [extensionTarget];
-  const bundledAliasManifestName = await resolveBundledAliasManifestName(extensionTarget);
-  if (bundledAliasManifestName) {
-    lookupValues.push(bundledAliasManifestName);
-  }
-  const normalizedLookups = [
-    ...new Set(lookupValues.map((value) => normalizeExtensionNameForMatch(value)).filter((value) => value.length > 0))
-  ];
-  for (const lookup of normalizedLookups) {
-    const byName = installed.find((entry) => normalizeExtensionNameForMatch(entry.name) === lookup);
-    if (byName) {
-      return byName;
-    }
-    const byDirectory = installed.find((entry) => normalizeExtensionNameForMatch(entry.directory) === lookup);
-    if (byDirectory) {
-      return byDirectory;
-    }
-  }
-  return void 0;
-}
-function isExtensionEnabled(settings, name) {
-  const normalizedName = name.trim();
-  const enabled = new Set(normalizeStringList(settings.extensions.enabled));
-  const disabled = new Set(normalizeStringList(settings.extensions.disabled));
-  if (disabled.has(normalizedName)) {
-    return false;
+  return void 0;
+};
+var isExtensionEnabled = (settings, name) => {
+  const normalizedName = name.trim();
+  const enabled = new Set(normalizeStringList(settings.extensions.enabled));
+  const disabled = new Set(normalizeStringList(settings.extensions.disabled));
+  if (disabled.has(normalizedName)) {
+    return false;
   }
   if (enabled.size === 0) {
     return true;
   }
   return enabled.has(normalizedName);
-}
-function ensureActivated(settings, name) {
+};
+var ensureActivated = (settings, name) => {
   const normalizedName = name.trim();
   const enabled = new Set(normalizeStringList(settings.extensions.enabled));
   const disabled = new Set(normalizeStringList(settings.extensions.disabled));
@@ -4361,8 +4596,8 @@ function ensureActivated(settings, name) {
   settings.extensions.enabled = [...enabled].sort((left, right) => left.localeCompare(right));
   settings.extensions.disabled = [...disabled].sort((left, right) => left.localeCompare(right));
   return settings.extensions.enabled.join("\0") !== previousEnabled.join("\0") || settings.extensions.disabled.join("\0") !== previousDisabled.join("\0");
-}
-function ensureDeactivated(settings, name) {
+};
+var ensureDeactivated = (settings, name) => {
   const normalizedName = name.trim();
   const enabled = new Set(normalizeStringList(settings.extensions.enabled));
   const disabled = new Set(normalizeStringList(settings.extensions.disabled));
@@ -4373,8 +4608,8 @@ function ensureDeactivated(settings, name) {
   settings.extensions.enabled = [...enabled].sort((left, right) => left.localeCompare(right));
   settings.extensions.disabled = [...disabled].sort((left, right) => left.localeCompare(right));
   return settings.extensions.enabled.join("\0") !== previousEnabled.join("\0") || settings.extensions.disabled.join("\0") !== previousDisabled.join("\0");
-}
-function clearExtensionState(settings, name) {
+};
+var clearExtensionState = (settings, name) => {
   const normalizedName = name.trim();
   const enabled = new Set(normalizeStringList(settings.extensions.enabled));
   const disabled = new Set(normalizeStringList(settings.extensions.disabled));
@@ -4385,31 +4620,18 @@ function clearExtensionState(settings, name) {
   settings.extensions.enabled = [...enabled].sort((left, right) => left.localeCompare(right));
   settings.extensions.disabled = [...disabled].sort((left, right) => left.localeCompare(right));
   return settings.extensions.enabled.join("\0") !== previousEnabled.join("\0") || settings.extensions.disabled.join("\0") !== previousDisabled.join("\0");
-}
-function suggestLifecycleActionTarget(target) {
+};
+var suggestLifecycleActionTarget = (target) => {
   const normalizedTarget = target.trim().toLowerCase();
-  const exactMatch = LIFECYCLE_ACTION_TARGETS.find(([candidate]) => candidate === normalizedTarget);
-  if (exactMatch) {
-    return { action: exactMatch[1], flag: exactMatch[2] };
-  }
-  const maxDistance = normalizedTarget.length <= 4 ? 1 : 2;
-  let nearest = null;
-  for (const [candidate, action, flag] of LIFECYCLE_ACTION_TARGETS) {
-    const distance = levenshteinDistanceWithinLimit(normalizedTarget, candidate, maxDistance);
-    if (distance === null) {
-      continue;
-    }
-    if (nearest === null) {
-      nearest = { action, flag, distance };
-      continue;
-    }
-    if (distance < nearest.distance) {
-      nearest = { action, flag, distance };
-    }
-  }
-  return nearest === null ? null : { action: nearest.action, flag: nearest.flag };
-}
-function buildUnknownLifecycleActionError(target, options) {
+  const maxDistance = Math.min(2, Math.max(1, Math.ceil(normalizedTarget.length / 4)));
+  const nearest = LIFECYCLE_ACTION_TARGETS.map(([candidate, action, flag]) => ({
+    action,
+    flag,
+    distance: levenshteinDistanceWithinLimit(normalizedTarget, candidate, maxDistance)
+  })).filter((entry) => entry.distance !== null).sort((left, right) => left.distance - right.distance)[0];
+  return nearest ? { action: nearest.action, flag: nearest.flag } : null;
+};
+var buildUnknownLifecycleActionError = (target, options) => {
   const noun = options.vocabulary === "package" ? "package" : "extension";
   const suggestion = suggestLifecycleActionTarget(target);
   if (!suggestion) {
@@ -4432,7 +4654,7 @@ function buildUnknownLifecycleActionError(target, options) {
       ]
     }
   });
-}
+};
 var EXTENSION_ACTION_FLAG_SELECTORS = [
   ["install", "install"],
   ["uninstall", "uninstall"],
@@ -4449,31 +4671,19 @@ var EXTENSION_ACTION_FLAG_SELECTORS = [
   ["activate", "activate"],
   ["deactivate", "deactivate"]
 ];
-function resolveImplicitActionFromTarget(normalizedTarget) {
-  if (normalizedTarget === "doctor") {
-    return "doctor";
-  }
-  if (normalizedTarget === "reload") {
-    return "reload";
-  }
-  if (normalizedTarget === "catalog") {
-    return "catalog";
-  }
-  if (normalizedTarget === "init" || normalizedTarget === "scaffold") {
-    return "init";
-  }
-  if (normalizedTarget === "explore") {
-    return "explore";
-  }
-  if (normalizedTarget === "manage") {
-    return "manage";
-  }
-  if (normalizedTarget === "list" || normalizedTarget === "") {
-    return "explore";
-  }
-  return null;
-}
-function resolveAction(target, options) {
+var IMPLICIT_EXTENSION_ACTIONS = {
+  doctor: "doctor",
+  reload: "reload",
+  catalog: "catalog",
+  init: "init",
+  scaffold: "init",
+  explore: "explore",
+  manage: "manage",
+  list: "explore",
+  "": "explore"
+};
+var resolveImplicitActionFromTarget = (normalizedTarget) => IMPLICIT_EXTENSION_ACTIONS[normalizedTarget] ?? null;
+var resolveAction = (target, options) => {
   const selected = [
     ...new Set(EXTENSION_ACTION_FLAG_SELECTORS.filter(([flag]) => options[flag] === true).map(([, mappedAction]) => mappedAction))
   ];
@@ -4491,59 +4701,55 @@ function resolveAction(target, options) {
     throw new PmCliError("Extension action flags are mutually exclusive.", EXIT_CODE.USAGE);
   }
   return selected[0];
-}
-function resolveScope(options) {
+};
+var resolveScope = (options) => {
   const projectLike = options.project === true || options.local === true;
   const global = options.global === true;
   if (projectLike && global) {
     throw new PmCliError('Options "--project/--local" and "--global" are mutually exclusive.', EXIT_CODE.USAGE);
   }
   return global ? "global" : "project";
-}
-function resolveUpdateCheckResolution(managedEntry) {
-  if (!managedEntry) {
-    return {
-      status: "skipped_unmanaged",
-      reason: "extension_not_managed"
-    };
-  }
-  if (managedEntry.source.kind !== "github") {
-    return {
-      status: "skipped_non_github",
-      reason: `managed_source_kind_${managedEntry.source.kind}`
-    };
-  }
-  const updateError = typeof managedEntry.update_error === "string" ? managedEntry.update_error.trim() : "";
-  if (updateError.length > 0) {
-    return {
-      status: "failed",
-      reason: updateError
-    };
-  }
-  if (typeof managedEntry.last_update_check_at === "string" && managedEntry.last_update_check_at.trim().length > 0) {
-    if (managedEntry.update_available === true) {
-      return {
-        status: "checked",
-        reason: "update_available"
-      };
+};
+var EXTENSION_UPDATE_CHECK_RESOLVERS = [
+  (managedEntry) => managedEntry ? null : {
+    status: "skipped_unmanaged",
+    reason: "extension_not_managed"
+  },
+  (managedEntry) => managedEntry && managedEntry.source.kind !== "github" ? {
+    status: "skipped_non_github",
+    reason: `managed_source_kind_${managedEntry.source.kind}`
+  } : null,
+  (managedEntry) => {
+    const updateError = typeof managedEntry?.update_error === "string" ? managedEntry.update_error.trim() : "";
+    return updateError.length > 0 ? { status: "failed", reason: updateError } : null;
+  },
+  (managedEntry) => {
+    const entry = managedEntry;
+    const checkedAt = typeof entry.last_update_check_at === "string" ? entry.last_update_check_at.trim() : "";
+    if (checkedAt.length === 0) {
+      return null;
     }
-    if (managedEntry.update_available === false) {
-      return {
-        status: "checked",
-        reason: "up_to_date"
-      };
+    const reason = {
+      true: "update_available",
+      false: "up_to_date"
+    }[String(entry.update_available)] ?? "checked_without_commit_baseline";
+    return { status: "checked", reason };
+  }
+];
+var resolveUpdateCheckResolution = (managedEntry) => {
+  for (const resolve of EXTENSION_UPDATE_CHECK_RESOLVERS) {
+    const resolution = resolve(managedEntry);
+    if (resolution) {
+      return resolution;
     }
-    return {
-      status: "checked",
-      reason: "checked_without_commit_baseline"
-    };
   }
   return {
     status: "not_checked",
     reason: "no_update_check_recorded"
   };
-}
-function buildInstalledExtensionSummary(identity, scope, managedEntry, updateCheck) {
+};
+var buildInstalledExtensionSummary = (identity, scope, managedEntry, updateCheck) => {
+  const managed = managedEntry ?? {};
   return {
     name: identity.name,
     directory: identity.directory,
@@ -4555,92 +4761,106 @@ function buildInstalledExtensionSummary(identity, scope, managedEntry, updateChe
     runtime_active: null,
     activation_status: "unknown",
     managed: Boolean(managedEntry),
-    source: managedEntry?.source,
-    update_available: managedEntry?.update_available,
-    last_update_check_at: managedEntry?.last_update_check_at,
-    last_update_remote_commit: managedEntry?.last_update_remote_commit,
-    update_error: managedEntry?.update_error,
+    source: managed.source,
+    update_available: managed.update_available,
+    last_update_check_at: managed.last_update_check_at,
+    last_update_remote_commit: managed.last_update_remote_commit,
+    update_error: managed.update_error,
     update_check_status: updateCheck.status,
     update_check_reason: updateCheck.reason
   };
-}
-async function listInstalledExtensions(extensionsRoot, scope, settings, state) {
+};
+var buildMissingManifestInspection = (directoryName, scope, settings, managedEntry) => {
+  const managed = Object.assign({
+    name: directoryName,
+    manifest_version: "unknown",
+    manifest_entry: "unknown"
+  }, managedEntry);
+  const enabled = managedEntry ? isExtensionEnabled(settings, managedEntry.name) : false;
+  return {
+    warning: `extension_manifest_missing:${scope}:${directoryName}`,
+    summary: buildInstalledExtensionSummary({
+      name: managed.name,
+      directory: directoryName,
+      version: managed.manifest_version,
+      entry: managed.manifest_entry,
+      enabled
+    }, scope, managedEntry, resolveUpdateCheckResolution(managedEntry))
+  };
+};
+var inspectInstalledExtensionDirectory = async (extensionsRoot, directoryName, scope, settings, managedByName, managedByDirectory) => {
+  const extensionDirectory = path8.join(extensionsRoot, directoryName);
+  const manifestPath = path8.join(extensionDirectory, "manifest.json");
+  const managedDirectoryEntry = managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
+  if (!await pathExists(manifestPath)) {
+    return buildMissingManifestInspection(directoryName, scope, settings, managedDirectoryEntry);
+  }
+  const invalidJson = /* @__PURE__ */ Symbol("invalid-extension-manifest-json");
+  const rawManifest = await fs8.readFile(manifestPath, "utf8").then((contents) => JSON.parse(contents)).catch(() => invalidJson);
+  if (rawManifest === invalidJson) {
+    return {
+      warning: `extension_manifest_invalid_json:${scope}:${directoryName}`
+    };
+  }
+  const manifest = parseExtensionManifest(rawManifest);
+  if (!manifest) {
+    return { warning: `extension_manifest_invalid:${scope}:${directoryName}` };
+  }
+  const managedEntry = managedByName.get(normalizeExtensionNameForMatch(manifest.name)) ?? managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
+  return {
+    summary: buildInstalledExtensionSummary({
+      name: manifest.name,
+      directory: directoryName,
+      version: manifest.version,
+      entry: manifest.entry,
+      enabled: isExtensionEnabled(settings, manifest.name)
+    }, scope, managedEntry, resolveUpdateCheckResolution(managedEntry))
+  };
+};
+var listInstalledExtensions = async (extensionsRoot, scope, settings, state) => {
   if (!await pathExists(extensionsRoot)) {
     return {
       extensions: [],
       warnings: []
     };
   }
-  const entries = await fs6.readdir(extensionsRoot, { withFileTypes: true });
+  const entries = await fs8.readdir(extensionsRoot, { withFileTypes: true });
   const directories = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
-  const managedByName = /* @__PURE__ */ new Map();
-  const managedByDirectory = /* @__PURE__ */ new Map();
-  for (const managedEntry of state.entries) {
-    managedByName.set(normalizeExtensionNameForMatch(managedEntry.name), managedEntry);
-    managedByDirectory.set(normalizeExtensionNameForMatch(managedEntry.directory), managedEntry);
-  }
+  const managedByName = new Map(state.entries.map((managedEntry) => [
+    normalizeExtensionNameForMatch(managedEntry.name),
+    managedEntry
+  ]));
+  const managedByDirectory = new Map(state.entries.map((managedEntry) => [
+    normalizeExtensionNameForMatch(managedEntry.directory),
+    managedEntry
+  ]));
   const warnings = [];
   const summaries = [];
   for (const directoryName of directories) {
-    const extensionDirectory = path6.join(extensionsRoot, directoryName);
-    const manifestPath = path6.join(extensionDirectory, "manifest.json");
-    if (!await pathExists(manifestPath)) {
-      warnings.push(`extension_manifest_missing:${scope}:${directoryName}`);
-      const managedEntry2 = managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
-      summaries.push(buildInstalledExtensionSummary({
-        name: managedEntry2?.name ?? directoryName,
-        directory: directoryName,
-        version: managedEntry2?.manifest_version ?? "unknown",
-        entry: managedEntry2?.manifest_entry ?? "unknown",
-        enabled: managedEntry2 ? isExtensionEnabled(settings, managedEntry2.name) : false
-      }, scope, managedEntry2, resolveUpdateCheckResolution(managedEntry2)));
-      continue;
+    const inspected = await inspectInstalledExtensionDirectory(extensionsRoot, directoryName, scope, settings, managedByName, managedByDirectory);
+    if (inspected.warning) {
+      warnings.push(inspected.warning);
     }
-    let rawManifest;
-    try {
-      rawManifest = JSON.parse(await fs6.readFile(manifestPath, "utf8"));
-    } catch {
-      warnings.push(`extension_manifest_invalid_json:${scope}:${directoryName}`);
-      continue;
+    if (inspected.summary) {
+      summaries.push(inspected.summary);
     }
-    const manifest = parseExtensionManifest(rawManifest);
-    if (!manifest) {
-      warnings.push(`extension_manifest_invalid:${scope}:${directoryName}`);
-      continue;
-    }
-    const managedEntry = managedByName.get(normalizeExtensionNameForMatch(manifest.name)) ?? managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
-    summaries.push(buildInstalledExtensionSummary({
-      name: manifest.name,
-      directory: directoryName,
-      version: manifest.version,
-      entry: manifest.entry,
-      enabled: isExtensionEnabled(settings, manifest.name)
-    }, scope, managedEntry, resolveUpdateCheckResolution(managedEntry)));
   }
   return {
     extensions: summaries.sort((left, right) => left.name.localeCompare(right.name)),
     warnings: warnings.sort((left, right) => left.localeCompare(right))
   };
-}
+};
 var extensionRuntimeProbeQueue = createSerialQueue();
-function summarizeRuntimeCommandPathsForExtension(extensionName, installed) {
+var summarizeRuntimeCommandPathsForExtension = (extensionName, installed) => {
   const normalizedName = normalizeExtensionNameForMatch(extensionName);
   const entry = installed.find((candidate) => normalizeExtensionNameForMatch(candidate.name) === normalizedName);
   return {
     command_paths: [...entry?.command_paths ?? []].sort((left, right) => left.localeCompare(right)),
     action_paths: [...entry?.action_paths ?? []].sort((left, right) => left.localeCompare(right))
   };
-}
-function resolveCommandDiscoveryPackageName(extensionName, source) {
-  if (typeof source.package === "string" && source.package.trim().length > 0) {
-    return source.package.trim();
-  }
-  if (source.kind === "builtin" && typeof source.name === "string" && source.name.trim().length > 0) {
-    return source.name.trim();
-  }
-  return extensionName;
-}
-function buildInstallCommandDiscovery(extensionName, source, commandSummary, activationFailure) {
+};
+var resolveCommandDiscoveryPackageName = (extensionName, source) => [source.package, source.kind === "builtin" ? source.name : void 0].find((candidate) => candidate?.trim())?.trim() ?? extensionName;
+var buildInstallCommandDiscovery = (extensionName, source, commandSummary, activationFailure) => {
   const helpCommands = commandSummary.command_paths.map((commandPath) => `pm ${commandPath} --help`);
   const sdkDependencyMissing = activationFailure?.error.toLowerCase().includes("@unbrained/pm-cli") === true;
   const nextSteps = commandSummary.command_paths.length > 0 ? [...helpCommands] : [
@@ -4658,42 +4878,40 @@ function buildInstallCommandDiscovery(extensionName, source, commandSummary, act
     next_steps: nextSteps,
     ...sdkDependencyMissing ? { sdk_dependency_status: "missing" } : {}
   };
-}
-function summarizeActivationFailureForDiagnostics(failure) {
-  const trace = failure.trace ? {
-    method: failure.trace.method,
-    registration_index: failure.trace.registration_index,
-    expected_schema: failure.trace.expected_schema,
-    ...failure.trace.command ? { command: failure.trace.command } : {},
-    ...failure.trace.capability ? { capability: failure.trace.capability } : {},
-    ...failure.trace.missing_capability ? { missing_capability: failure.trace.missing_capability } : {},
-    ...failure.trace.hint ? { hint: failure.trace.hint } : {}
-  } : void 0;
-  return {
+};
+var summarizeActivationFailureForDiagnostics = (failure) => {
+  const trace = failure.trace;
+  const summary = {
     layer: failure.layer,
     name: failure.name,
     entry_path: failure.entry_path,
-    error: failure.error,
-    ...failure.trace?.missing_capability ? { missing_capability: failure.trace.missing_capability } : {},
-    ...failure.trace?.hint ? { hint: failure.trace.hint } : {},
-    ...trace ? { trace } : {}
+    error: failure.error
   };
-}
-function collectActivationFailureDiagnostics(failures) {
+  if (!trace)
+    return summary;
+  summary.trace = Object.fromEntries(Object.entries(trace).filter(([, value]) => value !== void 0));
+  if (trace.missing_capability) {
+    summary.missing_capability = trace.missing_capability;
+  }
+  if (trace.hint)
+    summary.hint = trace.hint;
+  return summary;
+};
+var collectActivationFailureDiagnostics = (failures) => {
   return failures.map((failure) => summarizeActivationFailureForDiagnostics(failure)).sort((left, right) => `${left.layer}:${left.name}`.localeCompare(`${right.layer}:${right.name}`));
-}
-function findActivationFailureByName(extensionName, failures, layer) {
+};
+var findActivationFailureByName = (extensionName, failures, layer) => {
   const normalizedName = normalizeExtensionNameForMatch(extensionName);
   return failures.find((failure) => (layer === void 0 || failure.layer === layer) && normalizeExtensionNameForMatch(failure.name) === normalizedName);
-}
-function resolveInstallRuntimeActivationStatus(extensionName, scope, runtimeInstalled, installActivationFailure) {
+};
+var resolveInstallRuntimeActivationStatus = (extensionName, scope, runtimeInstalled, installActivationFailure) => {
   const runtimeInstalledExtension = runtimeInstalled.find((entry) => entry.scope === scope && normalizeExtensionNameForMatch(entry.name) === normalizeExtensionNameForMatch(extensionName));
   return runtimeInstalledExtension?.activation_status ?? (installActivationFailure ? "failed" : "unknown");
-}
-async function probeRuntimeCommandPathsForInstall(pmRoot, settings, refreshedInstalled, global) {
+};
+var probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled, global) => {
   return extensionRuntimeProbeQueue.enqueue(async () => {
     const originalPackageRoot = process.env.PM_CLI_PACKAGE_ROOT;
-    process.env.PM_CLI_PACKAGE_ROOT = path6.resolve(path6.dirname(fileURLToPath2(import.meta.url)), "../../..");
+    process.env.PM_CLI_PACKAGE_ROOT = resolvePmPackageRootFromModule(import.meta.url, ["../.."]);
     try {
       const loadResult = await loadExtensions({
         pmRoot,
@@ -4731,61 +4949,8 @@ async function probeRuntimeCommandPathsForInstall(pmRoot, settings, refreshedIns
       }
     }
   });
-}
-async function checkGithubUpdate(source, gitCommandRunner = runGitCommand) {
-  const checkedAt = nowIso();
-  if (source.kind !== "github" || !source.repository) {
-    return {
-      checked_at: checkedAt,
-      available: null,
-      error: "not_a_github_managed_source"
-    };
-  }
-  try {
-    const ref = source.ref && source.ref.trim().length > 0 ? source.ref.trim() : "HEAD";
-    const output3 = await gitCommandRunner([
-      "ls-remote",
-      source.repository,
-      ref
-    ]);
-    const firstLine = output3.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0);
-    if (!firstLine) {
-      return {
-        checked_at: checkedAt,
-        available: null,
-        error: "no_remote_reference_found"
-      };
-    }
-    const [remoteCommit] = firstLine.split(/\s+/);
-    if (typeof remoteCommit !== "string" || remoteCommit.length === 0) {
-      return {
-        checked_at: checkedAt,
-        available: null,
-        error: "invalid_remote_reference"
-      };
-    }
-    if (typeof source.commit === "string" && source.commit.trim().length > 0) {
-      return {
-        checked_at: checkedAt,
-        remote_commit: remoteCommit,
-        available: remoteCommit !== source.commit.trim()
-      };
-    }
-    return {
-      checked_at: checkedAt,
-      remote_commit: remoteCommit,
-      available: null,
-      error: "missing_installed_commit"
-    };
-  } catch (error) {
-    return {
-      checked_at: checkedAt,
-      available: null,
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-}
-async function adoptUnmanagedExtensions(extensionsRoot, scope, installedExtensions, state) {
+};
+var adoptUnmanagedExtensions = async (extensionsRoot, scope, installedExtensions, state) => {
   const unmanagedCandidates = installedExtensions.filter((entry) => !entry.managed);
   const sortedCandidates = [...unmanagedCandidates].sort((left, right) => {
     const byName = left.name.localeCompare(right.name);
@@ -4797,7 +4962,7 @@ async function adoptUnmanagedExtensions(extensionsRoot, scope, installedExtensio
   let nextState = state;
   const adoptedEntries = [];
   for (const candidate of sortedCandidates) {
-    const extensionDirectory = path6.join(extensionsRoot, candidate.directory);
+    const extensionDirectory = path8.join(extensionsRoot, candidate.directory);
     const validated = await validateExtensionDirectory(extensionDirectory);
     const now = nowIso();
     const sourceRecord = {
@@ -4833,8 +4998,8 @@ async function adoptUnmanagedExtensions(extensionsRoot, scope, installedExtensio
     unmanaged_candidates: sortedCandidates,
     already_managed_count: installedExtensions.length - unmanagedCandidates.length
   };
-}
-function resolveExtensionRootsForScope(scope, global) {
+};
+var resolveExtensionRootsForScope = (scope, global) => {
   const pmRoot = resolvePmRoot(process.cwd(), global.path);
   const roots = resolveExtensionRoots(pmRoot, process.cwd());
   const settingsRoot = scope === "global" ? resolveGlobalPmRoot(process.cwd()) : pmRoot;
@@ -4846,58 +5011,56 @@ function resolveExtensionRootsForScope(scope, global) {
     selected_root: selectedRoot,
     roots
   };
-}
-function resolveGithubOption(options) {
-  if (typeof options.gh === "string" && typeof options.github === "string" && options.gh.trim() !== options.github.trim()) {
+};
+var resolveGithubOption = (options) => {
+  const values = [options.gh, options.github].filter((value) => typeof value === "string").map((value) => value.trim()).filter(Boolean);
+  const uniqueValues = [...new Set(values)];
+  if (uniqueValues.length > 1) {
     throw new PmCliError('Options "--gh" and "--github" must match when both are provided.', EXIT_CODE.USAGE);
   }
-  if (typeof options.gh === "string" && options.gh.trim().length > 0) {
-    return options.gh.trim();
-  }
-  if (typeof options.github === "string" && options.github.trim().length > 0) {
-    return options.github.trim();
-  }
-  return void 0;
-}
-function getLifecycleActionFlag(action) {
+  return uniqueValues[0];
+};
+var getLifecycleActionFlag = (action) => {
   return LIFECYCLE_ACTION_FLAGS[action];
-}
-function requireTarget(target, action, options = {}) {
-  const normalized = target?.trim();
-  if (!normalized) {
-    if (action === "init") {
-      throw new PmCliError('Action "init" requires a scaffold target path (for example: pm package init ./my-package or pm extension init ./my-extension).', EXIT_CODE.USAGE);
+};
+var throwMissingLifecycleTarget = (action, options) => {
+  const noun = options.vocabulary === "package" ? "package" : "extension";
+  const targetName = action === "install" ? "source" : "name";
+  const targetLabel = `${noun} ${targetName}`;
+  const actionFlag = getLifecycleActionFlag(action);
+  const commandTarget = `<${targetName}>`;
+  const command = `pm ${noun} ${actionFlag} ${commandTarget}`;
+  throw new PmCliError(`Action "${action}" requires ${targetLabel} input.`, EXIT_CODE.USAGE, {
+    code: "missing_lifecycle_target",
+    required: `Provide a ${targetName} target for ${action}.`,
+    examples: [
+      `pm ${noun} ${action} ${commandTarget}`,
+      command,
+      `pm ${noun} --help`
+    ],
+    recovery: {
+      attempted_command: `pm ${noun} ${action}`,
+      suggested_retry: command,
+      fallback_candidates: [
+        {
+          source: "lifecycle_action",
+          command,
+          reason: `flag-form ${action} command with required ${targetName} target`
+        }
+      ]
     }
-    const noun = options.vocabulary === "package" ? "package" : "extension";
-    const targetName = action === "install" ? "source" : "name";
-    const targetLabel = `${noun} ${targetName}`;
-    const actionFlag = getLifecycleActionFlag(action);
-    const commandTarget = `<${targetName}>`;
-    const command = `pm ${noun} ${actionFlag} ${commandTarget}`;
-    throw new PmCliError(`Action "${action}" requires ${targetLabel} input.`, EXIT_CODE.USAGE, {
-      code: "missing_lifecycle_target",
-      required: `Provide a ${targetName} target for ${action}.`,
-      examples: [
-        `pm ${noun} ${action} ${commandTarget}`,
-        command,
-        `pm ${noun} --help`
-      ],
-      recovery: {
-        attempted_command: `pm ${noun} ${action}`,
-        suggested_retry: command,
-        fallback_candidates: [
-          {
-            source: "lifecycle_action",
-            command,
-            reason: `flag-form ${action} command with required ${targetName} target`
-          }
-        ]
-      }
-    });
+  });
+};
+var requireTarget = (target, action, options = {}) => {
+  const normalized = target?.trim();
+  if (normalized)
+    return normalized;
+  if (action === "init") {
+    throw new PmCliError('Action "init" requires a scaffold target path (for example: pm package init ./my-package or pm extension init ./my-extension).', EXIT_CODE.USAGE);
   }
-  return normalized;
-}
-function collectGlobalOutputOverrideDoctorWarnings(activationResult) {
+  return throwMissingLifecycleTarget(action, options);
+};
+var collectGlobalOutputOverrideDoctorWarnings = (activationResult) => {
   const warnings = [];
   for (const entry of activationResult.services.overrides) {
     if (entry.service !== "output_format") {
@@ -4909,31 +5072,21 @@ function collectGlobalOutputOverrideDoctorWarnings(activationResult) {
     warnings.push(`extension_output_renderer_override_global:${entry.format}:${entry.layer}:${entry.name}`);
   }
   return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
-}
-function collectSchemaNarrowActivationDoctorWarnings(loadResult, activationResult) {
-  const schemaContributors = /* @__PURE__ */ new Set();
-  for (const entry of activationResult.registrations.item_types) {
-    if (entry.types.length > 0) {
-      schemaContributors.add(`${entry.layer}:${normalizeExtensionNameForMatch(entry.name)}`);
-    }
-  }
-  for (const entry of activationResult.registrations.item_fields) {
-    if (entry.fields.length > 0) {
-      schemaContributors.add(`${entry.layer}:${normalizeExtensionNameForMatch(entry.name)}`);
-    }
-  }
-  const warnings = [];
-  for (const extension of loadResult.loaded) {
-    if ((extension.activation?.commands ?? []).length === 0) {
-      continue;
-    }
-    if (schemaContributors.has(`${extension.layer}:${normalizeExtensionNameForMatch(extension.name)}`)) {
-      warnings.push(`extension_schema_narrow_activation:${extension.layer}:${extension.name}`);
-    }
-  }
-  return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
-}
-function assertExtensionActionOptionScope(action, options) {
+};
+var collectSchemaNarrowActivationDoctorWarnings = (loadResult, activationResult) => {
+  const schemaContributors = new Set([
+    ...activationResult.registrations.item_types.map((entry) => ({
+      entry,
+      count: entry.types.length
+    })),
+    ...activationResult.registrations.item_fields.map((entry) => ({
+      entry,
+      count: entry.fields.length
+    }))
+  ].filter(({ count }) => count > 0).map(({ entry }) => `${entry.layer}:${normalizeExtensionNameForMatch(entry.name)}`));
+  return loadResult.loaded.filter((extension) => (extension.activation?.commands ?? []).length > 0).filter((extension) => schemaContributors.has(`${extension.layer}:${normalizeExtensionNameForMatch(extension.name)}`)).map((extension) => `extension_schema_narrow_activation:${extension.layer}:${extension.name}`).filter((warning, index, warnings) => warnings.indexOf(warning) === index).sort((left, right) => left.localeCompare(right));
+};
+var assertExtensionActionOptionScope = (action, options) => {
   const guards = [
     {
       triggered: options.strictExit === true || options.failOnWarn === true,
@@ -4976,86 +5129,115 @@ function assertExtensionActionOptionScope(action, options) {
       message: "--declarative is only valid with --init/--scaffold."
     }
   ];
-  for (const guard of guards) {
-    if (guard.triggered && !guard.allowed) {
-      throw new PmCliError(guard.message, EXIT_CODE.USAGE);
-    }
+  const invalidGuard = guards.find((guard) => guard.triggered && !guard.allowed);
+  if (invalidGuard) {
+    throw new PmCliError(invalidGuard.message, EXIT_CODE.USAGE);
   }
-}
-function resolveNormalizedExtensionTarget(target, action, options) {
-  const normalizedInput = target?.trim().toLowerCase();
-  if (action === "doctor" && normalizedInput === "doctor") {
-    return void 0;
-  }
-  if (action === "reload" && normalizedInput === "reload") {
-    return void 0;
-  }
-  if (action === "catalog" && normalizedInput === "catalog") {
-    return void 0;
-  }
-  const inferredInitAlias = action === "init" && options.init !== true && options.scaffold !== true && (normalizedInput === "init" || normalizedInput === "scaffold");
-  if (inferredInitAlias) {
-    return void 0;
+};
+var resolveNormalizedExtensionTarget = (target, action, options) => {
+  const normalizedInput = String(target ?? "").trim().toLowerCase();
+  const explicitInitAction = [options.init, options.scaffold].includes(true);
+  const aliases = {
+    doctor: ["doctor"],
+    reload: ["reload"],
+    catalog: ["catalog"],
+    init: explicitInitAction ? [] : ["init", "scaffold"]
+  };
+  return (aliases[action] ?? []).includes(normalizedInput) ? void 0 : target;
+};
+var resolveExtensionResultRoots = (ctx) => {
+  const projectedCatalog = [
+    ctx.action === "catalog",
+    typeof ctx.options.fields === "string",
+    String(ctx.options.fields).trim().length > 0
+  ].every(Boolean);
+  return projectedCatalog ? {
+    project: "project",
+    global: "global",
+    selected: ctx.scope,
+    settings_root: "project"
+  } : {
+    project: ctx.resolvedRoots.roots.project,
+    global: ctx.resolvedRoots.roots.global,
+    selected: ctx.resolvedRoots.selected_root,
+    settings_root: ctx.resolvedRoots.settings_root
+  };
+};
+var buildExtensionActionResult = (ctx, details, ok) => {
+  const result = {
+    ok,
+    action: ctx.action,
+    scope: ctx.scope,
+    roots: resolveExtensionResultRoots(ctx),
+    warnings: [...new Set(ctx.warnings)].sort((left, right) => left.localeCompare(right)),
+    details
+  };
+  if (ctx.action === "doctor") {
+    Object.defineProperty(result, NATIVE_OUTPUT_MARKER, {
+      value: true,
+      enumerable: false,
+      configurable: false
+    });
   }
-  return target;
-}
-async function runExtension(target, options, global) {
+  return result;
+};
+var runExtension = async (target, options, global) => {
   const action = resolveAction(target, options);
   assertExtensionActionOptionScope(action, options);
   const normalizedTarget = resolveNormalizedExtensionTarget(target, action, options);
   const scope = resolveScope(options);
   const resolvedRoots = resolveExtensionRootsForScope(scope, global);
   const warnings = [];
-  const withResult = (details, ok = true) => {
-    const result = {
-      ok,
-      action,
-      scope,
-      roots: action === "catalog" && typeof options.fields === "string" && options.fields.trim().length > 0 ? {
-        project: "project",
-        global: "global",
-        selected: scope,
-        settings_root: "project"
-      } : {
-        project: resolvedRoots.roots.project,
-        global: resolvedRoots.roots.global,
-        selected: resolvedRoots.selected_root,
-        settings_root: resolvedRoots.settings_root
-      },
-      warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
-      details
-    };
-    if (action === "doctor") {
-      Object.defineProperty(result, NATIVE_OUTPUT_MARKER, {
-        value: true,
-        enumerable: false,
-        configurable: false
-      });
-    }
-    return result;
-  };
-  const ctx = {
+  const actionContext = {
     action,
     normalizedTarget,
     scope,
     resolvedRoots,
     warnings,
     options,
-    global,
+    global
+  };
+  const withResult = (details, ok = true) => buildExtensionActionResult(actionContext, details, ok);
+  const ctx = {
+    ...actionContext,
     withResult
   };
-  return EXTENSION_ACTION_HANDLERS[action](ctx);
-}
-async function runExtensionInitAction(ctx) {
+  return await dispatchExtensionAction(ctx);
+};
+var buildExtensionScaffoldNextSteps = (scaffold, options) => {
+  const vocabulary = options.vocabulary ?? "extension";
+  const shellTargetPath = scaffold.target_path.replace(/\\/g, "/");
+  const quotedShellTargetPath = quoteCommandArg(shellTargetPath);
+  const dependencySteps = {
+    package: `Install dependencies: cd ${quotedShellTargetPath}, then run "npm install"`,
+    extension: `Install type-check dependencies: cd ${quotedShellTargetPath}, then run "npm install -D typescript @types/node @unbrained/pm-cli"`
+  };
+  const validationSteps = {
+    package: `Validate the package: cd ${quotedShellTargetPath}, then run "npm run typecheck" and "npm test"`,
+    extension: `Type-check the source (optional): cd ${quotedShellTargetPath}, then run "npx tsc --noEmit"`
+  };
+  const declarativeGuidance = [];
+  if ([vocabulary === "package", options.declarative === true].every(Boolean)) {
+    declarativeGuidance.push("Ensure the target workspace can resolve @unbrained/pm-cli before installing this declarative package.");
+  }
+  return [
+    dependencySteps[vocabulary],
+    ...declarativeGuidance,
+    `Install the scaffold: ${renderPmCommand(vocabulary === "package" ? ["install", "--project", shellTargetPath] : ["extension", "--install", "--project", shellTargetPath])}`,
+    `Smoke-test command path: pm ${scaffold.command_name}`,
+    validationSteps[vocabulary],
+    `Run diagnostics: ${vocabulary === "package" ? "pm package doctor" : "pm extension --doctor"} --project --detail summary`
+  ];
+};
+var runExtensionInitAction = async (ctx) => {
   const { action, normalizedTarget, options, withResult } = ctx;
   const githubOption = resolveGithubOption(options);
-  if (githubOption !== void 0 || typeof options.ref === "string" && options.ref.trim().length > 0) {
+  const disallowedSourceOptions = [githubOption, options.ref].filter((value) => typeof value === "string").map((value) => value.trim()).filter(Boolean);
+  if (disallowedSourceOptions.length > 0) {
     throw new PmCliError('Action "init" does not accept --gh/--github/--ref options.', EXIT_CODE.USAGE);
   }
   const scaffoldTarget = requireTarget(normalizedTarget, action, options);
   const scaffold = await scaffoldExtensionProject(scaffoldTarget, options.vocabulary ?? "extension", options.capability, options.declarative === true);
-  const quotedTargetPath = JSON.stringify(scaffold.target_path);
-  const quotedShellTargetPath = JSON.stringify(scaffold.target_path.replace(/\\/g, "/"));
   return withResult({
     scaffolded: scaffold.created_directory || scaffold.files.some((entry) => entry.status === "created"),
     extension: {
@@ -5063,35 +5245,14 @@ async function runExtensionInitAction(ctx) {
       command: scaffold.command_name
     },
     capability: scaffold.capability,
-    style: scaffold.style,
-    target_path: scaffold.target_path,
-    created_directory: scaffold.created_directory,
-    files: scaffold.files,
-    next_steps: [
-      // Extensions are authored AND loaded as TypeScript (ADR pm-2c28 / pm-m1uz):
-      // the manifest entry is ./index.ts and pm strips types on load (Node
-      // >=22.18), so there is no compile/build step — install dependencies, then
-      // install the scaffold directly.
-      ...options.vocabulary === "package" ? [
-        `Install dependencies: cd ${quotedShellTargetPath}, then run "npm install"`
-      ] : [
-        `Install type-check dependencies: cd ${quotedShellTargetPath}, then run "npm install -D typescript @types/node @unbrained/pm-cli"`
-      ],
-      ...options.vocabulary === "package" && options.declarative === true ? [
-        "Ensure the target workspace can resolve @unbrained/pm-cli before installing this declarative package."
-      ] : [],
-      `Install the scaffold: ${options.vocabulary === "package" ? "pm install --project" : "pm extension --install --project"} ${quotedTargetPath}`,
-      `Smoke-test command path: pm ${scaffold.command_name}`,
-      ...options.vocabulary === "package" ? [
-        `Validate the package: cd ${quotedShellTargetPath}, then run "npm run typecheck" and "npm test"`
-      ] : [
-        `Type-check the source (optional): cd ${quotedShellTargetPath}, then run "npx tsc --noEmit"`
-      ],
-      `Run diagnostics: ${options.vocabulary === "package" ? "pm package doctor" : "pm extension --doctor"} --project --detail summary`
-    ]
+    style: scaffold.style,
+    target_path: scaffold.target_path,
+    created_directory: scaffold.created_directory,
+    files: scaffold.files,
+    next_steps: buildExtensionScaffoldNextSteps(scaffold, options)
   });
-}
-async function runExtensionReloadAction(ctx) {
+};
+var runExtensionReloadAction = async (ctx) => {
   const { normalizedTarget, resolvedRoots, warnings, options, global, withResult } = ctx;
   if (normalizedTarget !== void 0) {
     throw new PmCliError('Action "reload" does not accept a target argument.', EXIT_CODE.USAGE);
@@ -5139,114 +5300,173 @@ async function runExtensionReloadAction(ctx) {
     warnings.push("extension_reload_watch_hint:watch_mode_requested_non_interactive_single_pass_only");
   }
   return withResult(details);
-}
-async function runExtensionCatalogAction(ctx) {
+};
+var runExtensionCatalogAction = async (ctx) => {
   const { normalizedTarget, scope, options, global, withResult } = ctx;
   if (typeof normalizedTarget === "string" && normalizedTarget.length > 0 && normalizedTarget !== "catalog") {
     throw new PmCliError('Action "catalog" does not accept a package target.', EXIT_CODE.USAGE);
   }
   return withResult(await buildBundledPackageCatalog(scope, global, options));
-}
-function buildInstallManagedSource(bundledAliasName, bundledPackageName, installSource, resolvedSource) {
+};
+var buildBundledInstallManagedSource = (alias, packageName) => ({
+  kind: "builtin",
+  input: alias,
+  location: alias,
+  name: alias,
+  ...packageName === null ? {} : { package: packageName }
+});
+var buildLocalInstallManagedSource = (source) => ({
+  kind: "local",
+  input: source.input,
+  location: source.absolute_path
+});
+var buildNpmInstallManagedSource = (source, resolved) => ({
+  kind: "npm",
+  input: source.input,
+  location: resolved.resolved_subpath ?? ".",
+  package: resolved.npm_package,
+  version: resolved.npm_version
+});
+var buildGithubInstallManagedSource = (source, resolved) => ({
+  kind: "github",
+  input: source.input,
+  location: resolved.resolved_subpath ?? source.subpath ?? ".",
+  repository: source.repository,
+  owner: source.owner,
+  repo: source.repo,
+  ref: source.ref,
+  subpath: resolved.resolved_subpath ?? source.subpath,
+  commit: resolved.commit
+});
+var buildInstallManagedSource = (bundledAliasName, bundledPackageName, installSource, resolvedSource) => {
   if (bundledAliasName) {
-    return {
-      kind: "builtin",
-      input: bundledAliasName,
-      location: bundledAliasName,
-      name: bundledAliasName,
-      ...bundledPackageName === null ? {} : { package: bundledPackageName }
-    };
+    return buildBundledInstallManagedSource(bundledAliasName, bundledPackageName);
   }
   if (installSource.kind === "local") {
-    return {
-      kind: "local",
-      input: installSource.input,
-      location: installSource.absolute_path
-    };
+    return buildLocalInstallManagedSource(installSource);
   }
   if (installSource.kind === "npm") {
-    return {
-      kind: "npm",
-      input: installSource.input,
-      location: resolvedSource.resolved_subpath ?? ".",
-      package: resolvedSource.npm_package,
-      version: resolvedSource.npm_version
-    };
+    return buildNpmInstallManagedSource(installSource, resolvedSource);
+  }
+  return buildGithubInstallManagedSource(installSource, resolvedSource);
+};
+var resolveManagedInstallTimestamps = (existing, manifestVersion, source, now) => {
+  if (!existing)
+    return { installed_at: now, updated_at: now };
+  if (existing.manifest_version !== manifestVersion) {
+    return { installed_at: existing.installed_at, updated_at: now };
+  }
+  if (!managedExtensionSourcesEquivalent(existing.source, source)) {
+    return { installed_at: existing.installed_at, updated_at: now };
   }
   return {
-    kind: "github",
-    input: installSource.input,
-    location: resolvedSource.resolved_subpath ?? installSource.subpath ?? ".",
-    repository: installSource.repository,
-    owner: installSource.owner,
-    repo: installSource.repo,
-    ref: installSource.ref,
-    subpath: resolvedSource.resolved_subpath ?? installSource.subpath,
-    commit: resolvedSource.commit
+    installed_at: existing.installed_at,
+    updated_at: existing.updated_at
   };
-}
-async function performExtensionInstallUnderLock(ctx, input3) {
-  const { scope, resolvedRoots, warnings, global, withResult } = ctx;
-  const { validated, destinationDirectoryName, bundledAliasName, bundledPackageName, installSource, resolvedSource } = input3;
+};
+var persistExtensionInstall = async (ctx, input3) => {
+  const { scope, resolvedRoots, warnings } = ctx;
+  const { validated, destinationDirectoryName } = input3;
   const settings = await readSettings(resolvedRoots.settings_root);
   const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
   warnings.push(...managedStateRead.warnings);
-  const destinationDirectory = path6.join(resolvedRoots.selected_root, destinationDirectoryName);
+  const destinationDirectory = path8.join(resolvedRoots.selected_root, destinationDirectoryName);
   const destinationExists = await pathExists(destinationDirectory);
   const installInPlace = await areDirectoriesEquivalent(validated.directory, destinationDirectory);
-  await fs6.mkdir(resolvedRoots.selected_root, { recursive: true });
-  if (!installInPlace) {
-    await copyExtensionDirectoryForInstall(validated.directory, destinationDirectory);
-  }
-  await ensureExtensionModuleTypeMarker(destinationDirectory);
-  const sourceRecord = buildInstallManagedSource(bundledAliasName, bundledPackageName, installSource, resolvedSource);
-  const now = nowIso();
-  const existingManagedEntry = managedStateRead.state.entries.find((entry) => normalizeExtensionNameForMatch(entry.name) === normalizeExtensionNameForMatch(validated.manifest.name));
-  const sourceUnchanged = existingManagedEntry !== void 0 && existingManagedEntry.manifest_version === validated.manifest.version && managedExtensionSourcesEquivalent(existingManagedEntry.source, sourceRecord);
-  const managedState = upsertManagedEntry(managedStateRead.state, {
-    name: validated.manifest.name,
-    directory: destinationDirectoryName,
-    scope,
-    manifest_version: validated.manifest.version,
-    manifest_entry: validated.manifest.entry,
-    capabilities: [...validated.manifest.capabilities],
-    installed_at: existingManagedEntry?.installed_at ?? now,
-    updated_at: sourceUnchanged ? existingManagedEntry.updated_at : now,
-    source: sourceRecord
-  });
-  await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
-  const activationChanged = ensureActivated(settings, validated.manifest.name);
-  if (activationChanged) {
-    await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
+  await fs8.mkdir(resolvedRoots.selected_root, { recursive: true });
+  const backupRoot = await fs8.mkdtemp(path8.join(resolvedRoots.selected_root, ".pm-extension-install-backup-"));
+  const backupDirectory = path8.join(backupRoot, "destination");
+  try {
+    const snapshot = await captureExtensionInstallSnapshot(resolvedRoots.selected_root, resolvedRoots.settings_root, destinationDirectory, destinationExists, backupDirectory);
+    const sourceRecord = buildInstallManagedSource(input3.bundledAliasName, input3.bundledPackageName, input3.installSource, input3.resolvedSource);
+    const existingManagedEntry = managedStateRead.state.entries.find((entry) => normalizeExtensionNameForMatch(entry.name) === normalizeExtensionNameForMatch(validated.manifest.name));
+    const timestamps = resolveManagedInstallTimestamps(existingManagedEntry, validated.manifest.version, sourceRecord, nowIso());
+    const managedState = upsertManagedEntry(managedStateRead.state, {
+      name: validated.manifest.name,
+      directory: destinationDirectoryName,
+      scope,
+      manifest_version: validated.manifest.version,
+      manifest_entry: validated.manifest.entry,
+      capabilities: [...validated.manifest.capabilities],
+      ...timestamps,
+      source: sourceRecord
+    });
+    const activationChanged = ensureActivated(settings, validated.manifest.name);
+    try {
+      if (!installInPlace) {
+        await copyExtensionDirectoryForInstall(validated.directory, destinationDirectory);
+      }
+      await ensureExtensionModuleTypeMarker(destinationDirectory);
+      await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
+      if (activationChanged) {
+        await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
+      }
+    } catch (error) {
+      try {
+        await restoreExtensionInstallSnapshot(snapshot);
+      } catch (rollbackError) {
+        throw new AggregateError([error, rollbackError], `Extension install failed: ${String(error)}; rollback failed: ${String(rollbackError)}`, { cause: rollbackError });
+      }
+      throw error;
+    }
+    return {
+      settings,
+      managedState,
+      sourceRecord,
+      destinationDirectory,
+      destinationExists,
+      installInPlace,
+      activationChanged
+    };
+  } finally {
+    await fs8.rm(backupRoot, { recursive: true, force: true }).catch(() => void 0);
   }
-  const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedState);
-  warnings.push(...refreshedInstalled.warnings);
-  const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, settings, refreshedInstalled.extensions, global);
-  warnings.push(...runtimeProbe.warnings);
-  const installedItemTypeDefinitions = runtimeProbe.item_type_registrations.filter((entry) => normalizeExtensionNameForMatch(entry.name) === normalizeExtensionNameForMatch(validated.manifest.name)).flatMap((entry) => entry.types.map((type) => ({ name: type.name, folder: type.folder })));
-  if (scope === "project" && installedItemTypeDefinitions.length > 0) {
-    await ensureTypeFolderScaffold(resolvedRoots.pm_root, installedItemTypeDefinitions, warnings, "install:type-folder");
+};
+var scaffoldInstalledExtensionItemTypes = async (ctx, extensionName, registrations) => {
+  const definitions = registrations.filter((entry) => normalizeExtensionNameForMatch(entry.name) === normalizeExtensionNameForMatch(extensionName)).flatMap((entry) => entry.types.map((type) => ({ name: type.name, folder: type.folder })));
+  if (ctx.scope === "project" && definitions.length > 0) {
+    await ensureTypeFolderScaffold(ctx.resolvedRoots.pm_root, definitions, ctx.warnings, "install:type-folder");
   }
-  const commandSummary = summarizeRuntimeCommandPathsForExtension(validated.manifest.name, runtimeProbe.installed);
-  const installActivationFailure = findActivationFailureByName(validated.manifest.name, runtimeProbe.activation_failures, scope);
-  const runtimeActivationStatus = resolveInstallRuntimeActivationStatus(validated.manifest.name, scope, runtimeProbe.installed, installActivationFailure);
-  const activated = !runtimeProbe.extensions_disabled && runtimeActivationStatus !== "failed";
+  return definitions;
+};
+var buildInstalledExtensionActivation = (ctx, extensionName, runtimeProbe, commandSummary, installedItemTypes) => {
+  const failure = findActivationFailureByName(extensionName, runtimeProbe.activation_failures, ctx.scope);
+  const status = resolveInstallRuntimeActivationStatus(extensionName, ctx.scope, runtimeProbe.installed, failure);
+  const activated = [!runtimeProbe.extensions_disabled, status === "ok"].every(Boolean);
   if (!activated) {
-    warnings.push(`extension_install_activation_failed:${scope}:${validated.manifest.name}:${runtimeActivationStatus}`);
+    ctx.warnings.push(`extension_install_activation_failed:${ctx.scope}:${extensionName}:${status}`);
   }
-  const verification = {
-    status: activated ? "ok" : "degraded",
-    target_pm_root: resolvedRoots.pm_root,
-    activation_status: runtimeActivationStatus,
+  const healthByActivation = {
+    true: { status: "ok", blocking_failure_count: 0 },
+    false: { status: "degraded", blocking_failure_count: 1 }
+  };
+  return {
     activated,
-    registered_commands: commandSummary.command_paths,
-    registered_actions: commandSummary.action_paths,
-    registered_item_types: installedItemTypeDefinitions,
-    health: {
-      status: activated ? "ok" : "degraded",
-      blocking_failure_count: activated ? 0 : 1
+    status,
+    failure,
+    verification: {
+      status: healthByActivation[String(activated)].status,
+      target_pm_root: ctx.resolvedRoots.pm_root,
+      activation_status: status,
+      activated,
+      registered_commands: commandSummary.command_paths,
+      registered_actions: commandSummary.action_paths,
+      registered_item_types: installedItemTypes,
+      health: healthByActivation[String(activated)]
     }
   };
+};
+var performExtensionInstallUnderLock = async (ctx, input3) => {
+  const { scope, resolvedRoots, warnings, global, withResult } = ctx;
+  const { validated, destinationDirectoryName } = input3;
+  const persisted = await persistExtensionInstall(ctx, input3);
+  const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, persisted.settings, persisted.managedState);
+  warnings.push(...refreshedInstalled.warnings);
+  const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, persisted.settings, refreshedInstalled.extensions, global);
+  warnings.push(...runtimeProbe.warnings);
+  const installedItemTypeDefinitions = await scaffoldInstalledExtensionItemTypes(ctx, validated.manifest.name, runtimeProbe.item_type_registrations);
+  const commandSummary = summarizeRuntimeCommandPathsForExtension(validated.manifest.name, runtimeProbe.installed);
+  const activation = buildInstalledExtensionActivation(ctx, validated.manifest.name, runtimeProbe, commandSummary, installedItemTypeDefinitions);
   return withResult({
     extension: {
       name: validated.manifest.name,
@@ -5255,74 +5475,80 @@ async function performExtensionInstallUnderLock(ctx, input3) {
       capabilities: validated.manifest.capabilities,
       directory: destinationDirectoryName
     },
-    source: sourceRecord,
-    destination_path: destinationDirectory,
-    overwritten: destinationExists && !installInPlace,
-    installed_in_place: installInPlace,
-    activated,
-    settings_changed: activationChanged,
-    runtime_activation_status: runtimeActivationStatus,
+    source: persisted.sourceRecord,
+    destination_path: persisted.destinationDirectory,
+    overwritten: [
+      persisted.destinationExists,
+      !persisted.installInPlace
+    ].every(Boolean),
+    installed_in_place: persisted.installInPlace,
+    activated: activation.activated,
+    settings_changed: persisted.activationChanged,
+    runtime_activation_status: activation.status,
     command_paths: commandSummary.command_paths,
     action_paths: commandSummary.action_paths,
-    command_discovery: buildInstallCommandDiscovery(validated.manifest.name, sourceRecord, commandSummary, installActivationFailure),
-    verification,
+    command_discovery: buildInstallCommandDiscovery(validated.manifest.name, persisted.sourceRecord, commandSummary, activation.failure),
+    verification: activation.verification,
     activation_diagnostics: {
       failed_count: runtimeProbe.activation_failures.length,
       failed: runtimeProbe.activation_failures,
-      installed_extension_failed: installActivationFailure ?? null
-    }
-  }, activated);
-}
-async function runExtensionInstallAction(ctx) {
-  const { action, normalizedTarget, resolvedRoots, warnings, options, global, withResult } = ctx;
-  const githubOption = resolveGithubOption(options);
-  const explicitSourceInput = githubOption ?? requireTarget(normalizedTarget, action, options);
-  if (typeof githubOption !== "string" && isBundledPackageInstallAllTarget(explicitSourceInput)) {
-    if (typeof options.ref === "string" && options.ref.trim().length > 0) {
-      throw new PmCliError('Action "install all" does not accept --ref.', EXIT_CODE.USAGE);
-    }
-    const aliases = await listBundledPackageAliases();
-    const packages = [];
-    for (const alias of aliases) {
-      packages.push({
-        alias,
-        result: await runExtension(alias, { ...options, install: true }, global)
-      });
+      installed_extension_failed: activation.failure ?? null
     }
-    for (const entry of packages) {
-      warnings.push(...entry.result.warnings);
-    }
-    const installedAll = packages.every((entry) => entry.result.ok);
-    return withResult({
-      installed_all: installedAll,
-      installed_count: packages.filter((entry) => entry.result.ok).length,
-      failed_count: packages.filter((entry) => !entry.result.ok).length,
-      packages: packages.map((entry) => ({
+  }, activation.activated);
+};
+var runBundledExtensionInstallAll = async (ctx) => {
+  const { options, global, warnings, withResult } = ctx;
+  if (typeof options.ref === "string" && options.ref.trim().length > 0) {
+    throw new PmCliError('Action "install all" does not accept --ref.', EXIT_CODE.USAGE);
+  }
+  const packages = [];
+  for (const alias of await listBundledPackageAliases()) {
+    packages.push({
+      alias,
+      result: await runExtension(alias, { ...options, install: true }, global)
+    });
+  }
+  warnings.push(...packages.flatMap((entry) => entry.result.warnings));
+  const installedAll = packages.every((entry) => entry.result.ok);
+  return withResult({
+    installed_all: installedAll,
+    installed_count: packages.filter((entry) => entry.result.ok).length,
+    failed_count: packages.filter((entry) => !entry.result.ok).length,
+    packages: packages.map((entry) => {
+      const details = entry.result.details;
+      return {
         alias: entry.alias,
         ok: entry.result.ok,
-        extension: entry.result.details.extension,
-        source: entry.result.details.source,
-        destination_path: entry.result.details.destination_path,
-        activated: entry.result.details.activated,
-        settings_changed: entry.result.details.settings_changed,
-        command_paths: entry.result.details.command_paths,
-        action_paths: entry.result.details.action_paths,
-        command_discovery: entry.result.details.command_discovery,
-        verification: entry.result.details.verification,
-        runtime_activation_status: entry.result.details.runtime_activation_status,
-        activation_diagnostics: entry.result.details.activation_diagnostics,
+        extension: details.extension,
+        source: details.source,
+        destination_path: details.destination_path,
+        activated: details.activated,
+        settings_changed: details.settings_changed,
+        command_paths: details.command_paths,
+        action_paths: details.action_paths,
+        command_discovery: details.command_discovery,
+        verification: details.verification,
+        runtime_activation_status: details.runtime_activation_status,
+        activation_diagnostics: details.activation_diagnostics,
         warnings: entry.result.warnings
-      }))
-    }, installedAll);
-  }
+      };
+    })
+  }, installedAll);
+};
+var resolveSingleExtensionInstallSource = async (explicitSourceInput, githubOption, ref) => {
   const bundledAliasSource = typeof githubOption === "string" ? null : await resolveBundledExtensionAliasSource(explicitSourceInput);
   const bundledAliasName = bundledAliasSource === null ? null : explicitSourceInput.trim().toLowerCase();
   const bundledPackageName = bundledAliasName === null ? null : await resolveBundledPackageNpmName(bundledAliasName);
   const sourceInput = bundledAliasSource ?? explicitSourceInput;
   const installSource = parseExtensionInstallSource(sourceInput, {
     forceGithub: typeof githubOption === "string",
-    ref: options.ref
+    ref
   });
+  return { bundledAliasName, bundledPackageName, installSource };
+};
+var runSingleExtensionInstall = async (ctx, explicitSourceInput, githubOption) => {
+  const { resolvedRoots } = ctx;
+  const { bundledAliasName, bundledPackageName, installSource } = await resolveSingleExtensionInstallSource(explicitSourceInput, githubOption, ctx.options.ref);
   const resolvedSource = await resolveInstallSource(installSource);
   try {
     const validated = await validateExtensionDirectory(resolvedSource.directory);
@@ -5340,8 +5566,19 @@ async function runExtensionInstallAction(ctx) {
       await resolvedSource.cleanup();
     }
   }
-}
-async function runExtensionAdoptAllAction(ctx) {
+};
+var runExtensionInstallAction = async (ctx) => {
+  const githubOption = resolveGithubOption(ctx.options);
+  const explicitSourceInput = githubOption ?? requireTarget(ctx.normalizedTarget, ctx.action, ctx.options);
+  if ([
+    githubOption === void 0,
+    isBundledPackageInstallAllTarget(explicitSourceInput)
+  ].every(Boolean)) {
+    return runBundledExtensionInstallAll(ctx);
+  }
+  return runSingleExtensionInstall(ctx, explicitSourceInput, githubOption);
+};
+var runExtensionAdoptAllAction = async (ctx) => {
   const { normalizedTarget, scope, resolvedRoots, warnings, options, withResult } = ctx;
   if (normalizedTarget !== void 0) {
     throw new PmCliError('Action "adopt-all" does not accept a target argument.', EXIT_CODE.USAGE);
@@ -5360,14 +5597,18 @@ async function runExtensionAdoptAllAction(ctx) {
   warnings.push(...refreshedInstalled.warnings);
   const triage = buildExtensionTriageSummary(scope, warnings, refreshedInstalled.extensions, options);
   warnings.push(...triage.warnings);
+  const refreshedByIdentity = new Map(refreshedInstalled.extensions.map((entry) => [
+    `${normalizeExtensionNameForMatch(entry.name)}:${normalizeExtensionNameForMatch(entry.directory)}`,
+    entry
+  ]));
+  const refreshedByDirectory = new Map(refreshedInstalled.extensions.map((entry) => [
+    normalizeExtensionNameForMatch(entry.directory),
+    entry
+  ]));
   const adoptedDetails = adoption.adopted_entries.map((entry) => {
-    const refreshedEntry = refreshedInstalled.extensions.find((candidate) => normalizeExtensionNameForMatch(candidate.name) === normalizeExtensionNameForMatch(entry.name) && normalizeExtensionNameForMatch(candidate.directory) === normalizeExtensionNameForMatch(entry.directory)) ?? /* c8 ignore next 3 -- fallback only matters if a manifest renames between adopt and refresh */
-    refreshedInstalled.extensions.find((candidate) => normalizeExtensionNameForMatch(candidate.directory) === normalizeExtensionNameForMatch(entry.directory));
-    return {
-      ...entry,
-      update_check_status: refreshedEntry?.update_check_status ?? null,
-      update_check_reason: refreshedEntry?.update_check_reason ?? null
-    };
+    const normalizedDirectory = normalizeExtensionNameForMatch(entry.directory);
+    const refreshedEntry = refreshedByIdentity.get(`${normalizeExtensionNameForMatch(entry.name)}:${normalizedDirectory}`) ?? refreshedByDirectory.get(normalizedDirectory);
+    return { ...entry, ...projectExtensionUpdateCheck(refreshedEntry) };
   });
   return withResult({
     adopted_all: adoptedDetails.length > 0,
@@ -5379,8 +5620,40 @@ async function runExtensionAdoptAllAction(ctx) {
     update_health_partial: triage.update_health_partial,
     update_health_coverage: triage.update_health_coverage
   });
-}
-async function runExtensionAdoptAction(ctx) {
+};
+var projectExtensionUpdateCheck = (entry) => {
+  return {
+    update_check_status: entry?.update_check_status ?? null,
+    update_check_reason: entry?.update_check_reason ?? null
+  };
+};
+var buildAdoptedExtensionSource = (githubOption, extensionTarget, extensionDirectory, ref) => {
+  if (githubOption === void 0) {
+    return {
+      kind: "local",
+      input: extensionTarget,
+      location: extensionDirectory
+    };
+  }
+  const parsed = parseExtensionInstallSource(githubOption, {
+    forceGithub: true,
+    ref
+  });
+  if (parsed.kind !== "github") {
+    throw new PmCliError(`Invalid GitHub shorthand "${githubOption}".`, EXIT_CODE.USAGE);
+  }
+  return {
+    kind: "github",
+    input: parsed.input,
+    location: parsed.subpath ?? ".",
+    repository: parsed.repository,
+    owner: parsed.owner,
+    repo: parsed.repo,
+    ref: parsed.ref,
+    subpath: parsed.subpath
+  };
+};
+var runExtensionAdoptAction = async (ctx) => {
   const { action, normalizedTarget, scope, resolvedRoots, warnings, options, withResult } = ctx;
   const extensionTarget = requireTarget(normalizedTarget, action, options);
   const githubOption = resolveGithubOption(options);
@@ -5403,32 +5676,10 @@ async function runExtensionAdoptAction(ctx) {
       }
     });
   }
-  const extensionDirectory = path6.join(resolvedRoots.selected_root, candidate.directory);
+  const extensionDirectory = path8.join(resolvedRoots.selected_root, candidate.directory);
   const validated = await validateExtensionDirectory(extensionDirectory);
   const now = nowIso();
-  const sourceRecord = githubOption === void 0 ? {
-    kind: "local",
-    input: extensionTarget,
-    location: extensionDirectory
-  } : (() => {
-    const parsed = parseExtensionInstallSource(githubOption, {
-      forceGithub: true,
-      ref: options.ref
-    });
-    if (parsed.kind !== "github") {
-      throw new PmCliError(`Invalid GitHub shorthand "${githubOption}".`, EXIT_CODE.USAGE);
-    }
-    return {
-      kind: "github",
-      input: parsed.input,
-      location: parsed.subpath ?? ".",
-      repository: parsed.repository,
-      owner: parsed.owner,
-      repo: parsed.repo,
-      ref: parsed.ref,
-      subpath: parsed.subpath
-    };
-  })();
+  const sourceRecord = buildAdoptedExtensionSource(githubOption, extensionTarget, extensionDirectory, options.ref);
   const managedState = upsertManagedEntry(managedStateRead.state, {
     name: validated.manifest.name,
     directory: candidate.directory,
@@ -5453,11 +5704,10 @@ async function runExtensionAdoptAction(ctx) {
       entry: validated.manifest.entry
     },
     source: sourceRecord,
-    update_check_status: refreshedEntry?.update_check_status ?? null,
-    update_check_reason: refreshedEntry?.update_check_reason ?? null
+    ...projectExtensionUpdateCheck(refreshedEntry)
   });
-}
-async function resolveRequiredInstalledExtension(ctx) {
+};
+var resolveRequiredInstalledExtension = async (ctx) => {
   const { action, normalizedTarget, scope, resolvedRoots, warnings, options } = ctx;
   const extensionTarget = requireTarget(normalizedTarget, action, options);
   const settings = await readSettings(resolvedRoots.settings_root);
@@ -5470,12 +5720,12 @@ async function resolveRequiredInstalledExtension(ctx) {
     throw new PmCliError(`Installed extension "${extensionTarget}" was not found in ${scope} scope.`, EXIT_CODE.NOT_FOUND);
   }
   return { settings, managedStateRead, candidate };
-}
-async function runExtensionUninstallAction(ctx) {
+};
+var runExtensionUninstallAction = async (ctx) => {
   const { resolvedRoots, withResult } = ctx;
   const { settings, managedStateRead, candidate } = await resolveRequiredInstalledExtension(ctx);
-  const destinationDirectory = path6.join(resolvedRoots.selected_root, candidate.directory);
-  await fs6.rm(destinationDirectory, { recursive: true, force: true });
+  const destinationDirectory = path8.join(resolvedRoots.selected_root, candidate.directory);
+  await fs8.rm(destinationDirectory, { recursive: true, force: true });
   const updatedState = {
     ...managedStateRead.state,
     updated_at: nowIso(),
@@ -5497,8 +5747,8 @@ async function runExtensionUninstallAction(ctx) {
     destination_path: destinationDirectory,
     settings_changed: stateChanged
   });
-}
-async function runExtensionActivateDeactivateAction(ctx) {
+};
+var runExtensionActivateDeactivateAction = async (ctx) => {
   const { action, resolvedRoots, withResult } = ctx;
   const { settings, candidate } = await resolveRequiredInstalledExtension(ctx);
   const settingsChanged = action === "activate" ? ensureActivated(settings, candidate.name) : ensureDeactivated(settings, candidate.name);
@@ -5517,37 +5767,65 @@ async function runExtensionActivateDeactivateAction(ctx) {
       disabled: [...settings.extensions.disabled]
     }
   });
-}
-function buildDoctorRemediation(baseRemediation, loadFailureCount, activationFailureCount, vocabulary, managedStateFix, isolationHint) {
+};
+var buildDoctorRemediation = (baseRemediation, loadFailureCount, activationFailureCount, vocabulary, managedStateFix, isolationHint) => {
+  const noun = vocabulary === "package" ? "package" : "extension";
+  const doctorAction = { package: "doctor", extension: "--doctor" }[noun];
+  const adoptedCount = managedStateFix?.adopted_entries.length ?? 0;
+  const conditionalEntries = [
+    [isolationHint !== null, isolationHint ?? ""],
+    [
+      loadFailureCount > 0,
+      `Run pm ${noun} explore --project and pm ${noun} explore --global to inspect load failures.`
+    ],
+    [
+      activationFailureCount > 0,
+      `Review activation failures in pm ${noun} ${doctorAction} --detail deep output.`
+    ],
+    [
+      adoptedCount > 0,
+      `Managed-state fix adopted ${adoptedCount} extension(s).`
+    ]
+  ];
   return [
     ...new Set([
       ...baseRemediation,
-      ...isolationHint === null ? [] : [isolationHint],
-      /* c8 ignore start -- vocabulary-specific remediation branches are copy-only variants */
-      ...loadFailureCount > 0 ? [
-        vocabulary === "package" ? "Run pm package explore --project and pm package explore --global to inspect load failures." : "Run pm extension --explore --project and pm extension --explore --global to inspect load failures."
-      ] : [],
-      ...activationFailureCount > 0 ? [
-        vocabulary === "package" ? "Review activation failures in pm package doctor --detail deep output." : "Review activation failures in pm extension --doctor --detail deep output."
-      ] : [],
-      /* c8 ignore stop */
-      ...managedStateFix && managedStateFix.adopted_entries.length > 0 ? [
-        `Managed-state fix adopted ${managedStateFix.adopted_entries.length} extension(s).`
-      ] : []
+      ...conditionalEntries.filter(([include]) => include).map(([, entry]) => entry)
     ].map((entry) => entry.trim()).filter((entry) => entry.length > 0))
   ];
-}
-function hasGlobalLayerDiagnostics(loadResult) {
+};
+var hasGlobalLayerDiagnostics = (loadResult) => {
   return loadResult.loaded.some((entry) => entry.layer === "global") || loadResult.failed.some((entry) => entry.layer === "global") || loadResult.warnings.some((warning) => warning.includes(":global:"));
-}
-function buildDoctorIsolationHint(scope, isolated, vocabulary, loadResult) {
+};
+var buildDoctorIsolationHint = (scope, isolated, vocabulary, loadResult) => {
   if (scope !== "project" || isolated || !hasGlobalLayerDiagnostics(loadResult)) {
     return null;
   }
   const noun = vocabulary === "package" ? "package" : "extension";
   return `Global ${noun} registrations are included in project diagnostics. For hermetic ${noun} smoke tests, rerun pm ${noun} doctor --project --isolated --detail deep --trace, or set PM_GLOBAL_PATH to a temporary directory for the whole test process.`;
-}
-function buildDoctorIsolationMetadata(scope, isolated, vocabulary, loadResult) {
+};
+var resolveDoctorInvocationOptions = (target, scope, options) => {
+  if (String(target ?? "").trim().length > 0) {
+    throw new PmCliError('Action "doctor" does not accept a target argument.', EXIT_CODE.USAGE);
+  }
+  const isolated = [options.isolated, options.ignoreGlobal].includes(true);
+  if ([isolated, scope === "global"].every(Boolean)) {
+    throw new PmCliError("--isolated and --ignore-global are only valid with project-scope doctor diagnostics.", EXIT_CODE.USAGE);
+  }
+  const detailMode = parseDoctorDetailMode(options.detail);
+  const includeTrace = options.trace === true;
+  if ([includeTrace, detailMode !== "deep"].every(Boolean)) {
+    throw new PmCliError("--trace requires --detail deep with --doctor.", EXIT_CODE.USAGE);
+  }
+  return { isolated, detailMode, includeTrace };
+};
+var applyDoctorManagedStateFix = async (ctx, installed, state) => {
+  if (ctx.options.fixManagedState !== true)
+    return { state, fix: null };
+  const fix = await adoptUnmanagedExtensions(ctx.resolvedRoots.selected_root, ctx.scope, installed, state);
+  return { state: fix.state, fix };
+};
+var buildDoctorIsolationMetadata = (scope, isolated, vocabulary, loadResult) => {
   const noun = vocabulary === "package" ? "package" : "extension";
   if (scope !== "project") {
     return {
@@ -5566,31 +5844,16 @@ function buildDoctorIsolationMetadata(scope, isolated, vocabulary, loadResult) {
     rerun_command: isolated ? null : isolatedCommand,
     pm_global_path_recipe: `PM_GLOBAL_PATH=$(mktemp -d) pm ${noun} doctor --project --detail deep --trace`
   };
-}
-async function runExtensionDoctorAction(ctx) {
+};
+var runExtensionDoctorAction = async (ctx) => {
   const { normalizedTarget, scope, resolvedRoots, warnings, options, global, withResult } = ctx;
-  if (normalizedTarget && normalizedTarget.trim().length > 0) {
-    throw new PmCliError('Action "doctor" does not accept a target argument.', EXIT_CODE.USAGE);
-  }
-  const isolated = options.isolated === true || options.ignoreGlobal === true;
-  if (isolated && scope === "global") {
-    throw new PmCliError("--isolated and --ignore-global are only valid with project-scope doctor diagnostics.", EXIT_CODE.USAGE);
-  }
-  const detailMode = parseDoctorDetailMode(options.detail);
-  const includeTrace = options.trace === true;
-  if (includeTrace && detailMode !== "deep") {
-    throw new PmCliError("--trace requires --detail deep with --doctor.", EXIT_CODE.USAGE);
-  }
+  const { isolated, detailMode, includeTrace } = resolveDoctorInvocationOptions(normalizedTarget, scope, options);
   const settings = await readSettings(resolvedRoots.settings_root);
   const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
   warnings.push(...managedStateRead.warnings);
   const installed = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedStateRead.state);
   warnings.push(...installed.warnings);
-  let managedState = managedStateRead.state;
-  const managedStateFix = options.fixManagedState === true ? await adoptUnmanagedExtensions(resolvedRoots.selected_root, scope, installed.extensions, managedStateRead.state) : null;
-  if (managedStateFix) {
-    managedState = managedStateFix.state;
-  }
+  const { state: managedState, fix: managedStateFix } = await applyDoctorManagedStateFix(ctx, installed.extensions, managedStateRead.state);
   const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedState);
   warnings.push(...refreshedInstalled.warnings);
   const loadResult = await loadExtensions({
@@ -5759,21 +6022,21 @@ async function runExtensionDoctorAction(ctx) {
           name: entry.name,
           entry_path: entry.entry_path,
           error: entry.error,
-          method: entry.trace?.method,
-          command: entry.trace?.command,
-          capability: entry.trace?.capability,
-          missing_capability: entry.trace?.missing_capability,
-          registration_index: entry.trace?.registration_index,
-          expected_schema: entry.trace?.expected_schema,
-          hint: entry.trace?.hint,
-          received: entry.trace?.received
+          method: entry.trace.method,
+          command: entry.trace.command,
+          capability: entry.trace.capability,
+          missing_capability: entry.trace.missing_capability,
+          registration_index: entry.trace.registration_index,
+          expected_schema: entry.trace.expected_schema,
+          hint: entry.trace.hint,
+          received: entry.trace.received
         }))
       };
     }
   }
   return withResult(details);
-}
-async function runExtensionDescribeAction(ctx) {
+};
+var runExtensionDescribeAction = async (ctx) => {
   const { normalizedTarget, scope, resolvedRoots, warnings, options, global, withResult } = ctx;
   const settings = await readSettings(resolvedRoots.settings_root);
   const loadResult = await loadExtensions({
@@ -5800,25 +6063,18 @@ async function runExtensionDescribeAction(ctx) {
     extensions: describeResult.extensions,
     union: describeResult.union
   });
-}
-async function runExtensionExploreManageAction(ctx) {
-  const { action, scope, resolvedRoots, warnings, options, global, withResult } = ctx;
-  const settings = await readSettings(resolvedRoots.settings_root);
-  const configuredPolicy = buildExtensionPolicyDetails(settings.extensions.policy);
-  const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
-  warnings.push(...managedStateRead.warnings);
-  const installed = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedStateRead.state);
-  warnings.push(...installed.warnings);
-  let managedState = managedStateRead.state;
-  const managedStateFix = action === "manage" && options.fixManagedState === true ? await adoptUnmanagedExtensions(resolvedRoots.selected_root, scope, installed.extensions, managedStateRead.state) : null;
-  if (managedStateFix) {
-    managedState = managedStateFix.state;
-  }
-  if (action === "manage") {
-    const updates = await Promise.all(managedState.entries.map(async (entry) => {
-      if (entry.source.kind !== "github") {
+};
+var prepareExploreManageState = async (ctx, installed, initialState) => {
+  let state = initialState;
+  let fix = null;
+  if ([ctx.action === "manage", ctx.options.fixManagedState === true].every(Boolean)) {
+    fix = await adoptUnmanagedExtensions(ctx.resolvedRoots.selected_root, ctx.scope, installed, initialState);
+    state = fix.state;
+  }
+  if (ctx.action === "manage") {
+    const entries = await mapWithFixedConcurrency(state.entries, GITHUB_UPDATE_CHECK_CONCURRENCY, async (entry) => {
+      if (entry.source.kind !== "github")
         return entry;
-      }
       const updateStatus = await checkGithubUpdate(entry.source);
       return {
         ...entry,
@@ -5827,55 +6083,85 @@ async function runExtensionExploreManageAction(ctx) {
         update_available: updateStatus.available,
         update_error: updateStatus.error
       };
-    }));
-    managedState = {
-      ...managedState,
+    });
+    state = {
+      ...state,
       updated_at: nowIso(),
-      entries: sortManagedEntries(updates)
+      entries: sortManagedEntries(entries)
     };
-    await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
+    await writeManagedExtensionState(ctx.resolvedRoots.selected_root, state);
   }
-  const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedState);
-  warnings.push(...refreshedInstalled.warnings);
-  if (action === "manage") {
-    const updateWarnings = refreshedInstalled.extensions.filter((entry) => entry.update_check_status === "failed").map((entry) => `extension_update_check_failed:${entry.name}`);
-    warnings.push(...updateWarnings);
+  return { state, fix };
+};
+var probeExploreManageRuntime = async (ctx, settings, installed) => {
+  const requested = [
+    ctx.action === "explore",
+    ctx.options.runtimeProbe === true
+  ].includes(true);
+  if (!requested) {
+    return {
+      installed,
+      failures: void 0,
+      summary: { requested: false, executed: false }
+    };
   }
-  let runtimeProbeSummary;
-  let runtimeInstalledExtensions = refreshedInstalled.extensions;
-  let runtimeActivationFailures;
-  if (action === "explore" || options.runtimeProbe === true) {
-    const loadResult = await loadExtensions({
-      pmRoot: resolvedRoots.pm_root,
-      settings,
-      cwd: process.cwd(),
-      noExtensions: global.noExtensions === true
-    });
-    const activationResult = await activateExtensions({
-      ...loadResult,
-      loaded: loadResult.loaded
-    });
-    warnings.push(...loadResult.warnings);
-    warnings.push(...activationResult.warnings);
-    runtimeInstalledExtensions = applyDoctorRuntimeActivationState(refreshedInstalled.extensions, loadResult, activationResult);
-    runtimeActivationFailures = collectActivationFailureDiagnostics(activationResult.failed);
-    runtimeProbeSummary = {
+  const loadResult = await loadExtensions({
+    pmRoot: ctx.resolvedRoots.pm_root,
+    settings,
+    cwd: process.cwd(),
+    noExtensions: ctx.global.noExtensions === true
+  });
+  const activationResult = await activateExtensions({
+    ...loadResult,
+    loaded: loadResult.loaded
+  });
+  ctx.warnings.push(...loadResult.warnings, ...activationResult.warnings);
+  return {
+    installed: applyDoctorRuntimeActivationState(installed, loadResult, activationResult),
+    failures: collectActivationFailureDiagnostics(activationResult.failed),
+    summary: {
       requested: true,
       executed: true,
-      reason: action === "explore" ? "explore_defaults_to_runtime_probe" : "runtime_probe_requested",
+      reason: ctx.action === "explore" ? "explore_defaults_to_runtime_probe" : "runtime_probe_requested",
       load_failure_count: loadResult.failed.length,
       activation_failure_count: activationResult.failed.length,
       warning_count: [
         .../* @__PURE__ */ new Set([...loadResult.warnings, ...activationResult.warnings])
       ].length,
       policy: loadResult.policy
-    };
-  } else if (action === "manage") {
-    runtimeProbeSummary = {
-      requested: false,
-      executed: false
-    };
+    }
+  };
+};
+var projectExploreManageFix = (fix, installed) => fix ? {
+  requested: true,
+  applied: fix.adopted_entries.length > 0,
+  adopted_count: fix.adopted_entries.length,
+  adopted_extensions: fix.adopted_entries.map((entry) => entry.name),
+  already_managed_count: fix.already_managed_count
+} : {
+  requested: false,
+  applied: false,
+  adopted_count: 0,
+  adopted_extensions: [],
+  already_managed_count: installed.filter((entry) => entry.managed).length
+};
+var runExtensionExploreManageAction = async (ctx) => {
+  const { action, scope, resolvedRoots, warnings, options, withResult } = ctx;
+  const settings = await readSettings(resolvedRoots.settings_root);
+  const configuredPolicy = buildExtensionPolicyDetails(settings.extensions.policy);
+  const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
+  warnings.push(...managedStateRead.warnings);
+  const installed = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedStateRead.state);
+  warnings.push(...installed.warnings);
+  const { state: managedState, fix: managedStateFix } = await prepareExploreManageState(ctx, installed.extensions, managedStateRead.state);
+  const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedState);
+  warnings.push(...refreshedInstalled.warnings);
+  if (action === "manage") {
+    const updateWarnings = refreshedInstalled.extensions.filter((entry) => entry.update_check_status === "failed").map((entry) => `extension_update_check_failed:${entry.name}`);
+    warnings.push(...updateWarnings);
   }
+  const runtimeProbe = await probeExploreManageRuntime(ctx, settings, refreshedInstalled.extensions);
+  const runtimeInstalledExtensions = runtimeProbe.installed;
   const triage = buildExtensionTriageSummary(scope, warnings, runtimeInstalledExtensions, options);
   warnings.push(...triage.warnings);
   const details = {
@@ -5887,33 +6173,21 @@ async function runExtensionExploreManageAction(ctx) {
     triage,
     policy: configuredPolicy
   };
-  if (runtimeActivationFailures !== void 0) {
+  if (runtimeProbe.failures !== void 0) {
     details.activation_diagnostics = {
-      failed_count: runtimeActivationFailures.length,
-      failed: runtimeActivationFailures
+      failed_count: runtimeProbe.failures.length,
+      failed: runtimeProbe.failures
     };
   }
   if (action === "explore") {
-    details.runtime_probe = runtimeProbeSummary;
+    details.runtime_probe = runtimeProbe.summary;
   }
   if (action === "manage") {
-    details.runtime_probe = runtimeProbeSummary;
-    details.managed_state_fix = managedStateFix !== null ? {
-      requested: true,
-      applied: managedStateFix.adopted_entries.length > 0,
-      adopted_count: managedStateFix.adopted_entries.length,
-      adopted_extensions: managedStateFix.adopted_entries.map((entry) => entry.name),
-      already_managed_count: managedStateFix.already_managed_count
-    } : {
-      requested: false,
-      applied: false,
-      adopted_count: 0,
-      adopted_extensions: [],
-      already_managed_count: runtimeInstalledExtensions.filter((entry) => entry.managed).length
-    };
+    details.runtime_probe = runtimeProbe.summary;
+    details.managed_state_fix = projectExploreManageFix(managedStateFix, runtimeInstalledExtensions);
   }
   return withResult(details);
-}
+};
 var EXTENSION_ACTION_HANDLERS = {
   init: runExtensionInitAction,
   install: runExtensionInstallAction,
@@ -5929,10 +6203,20 @@ var EXTENSION_ACTION_HANDLERS = {
   activate: runExtensionActivateDeactivateAction,
   deactivate: runExtensionActivateDeactivateAction
 };
+var requiresExtensionStateLock = (ctx) => [
+  ctx.action === "uninstall",
+  ctx.action === "manage",
+  ctx.action === "adopt",
+  ctx.action === "adopt-all",
+  ctx.action === "activate",
+  ctx.action === "deactivate",
+  [ctx.action === "doctor", ctx.options.fixManagedState === true].every(Boolean)
+].some(Boolean);
+var dispatchExtensionAction = (ctx) => requiresExtensionStateLock(ctx) ? withExtensionInstallLock(ctx.resolvedRoots.settings_root, `${ctx.action}-state`, () => EXTENSION_ACTION_HANDLERS[ctx.action](ctx)) : EXTENSION_ACTION_HANDLERS[ctx.action](ctx);
 
 // dist/sdk/workspace.js
 import { readFile, writeFile } from "node:fs/promises";
-import path7 from "node:path";
+import path9 from "node:path";
 var PM_GITIGNORE_START = "# pm-cli:runtime-cache:start";
 var PM_GITIGNORE_END = "# pm-cli:runtime-cache:end";
 var PM_GITIGNORE_BLOCK = [
@@ -5946,7 +6230,7 @@ function getPmGitignoreBlock() {
   return PM_GITIGNORE_BLOCK;
 }
 async function ensurePmGitignore(workspaceRoot) {
-  const gitignorePath = path7.join(workspaceRoot, ".gitignore");
+  const gitignorePath = path9.join(workspaceRoot, ".gitignore");
   let current = "";
   try {
     current = await readFile(gitignorePath, "utf8");
@@ -5970,15 +6254,9 @@ async function ensurePmGitignore(workspaceRoot) {
   return { path: gitignorePath, changed: true };
 }
 
-// dist/cli/commands/init.js
-import fs8 from "node:fs/promises";
-import path9 from "node:path";
-import readline2 from "node:readline/promises";
-import { stdin as input2, stdout as output2 } from "node:process";
-
-// dist/cli/commands/init-agent-guidance.js
-import fs7 from "node:fs/promises";
-import path8 from "node:path";
+// dist/sdk/init-agent-guidance.js
+import fs9 from "node:fs/promises";
+import path10 from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 var INIT_AGENT_GUIDANCE_MODE_VALUES = [
@@ -6007,13 +6285,33 @@ var AGENT_GUIDANCE_START_MARKER_PREFIX = "<!-- pm-cli:agent-guidance:start:";
 var AGENT_GUIDANCE_START_MARKER = `<!-- pm-cli:agent-guidance:start:v${AGENT_GUIDANCE_TEMPLATE_VERSION} -->`;
 var AGENT_GUIDANCE_END_MARKER = "<!-- pm-cli:agent-guidance:end -->";
 var AGENT_GUIDANCE_ADD_LATER_HINT = "Add workflow guidance later: pm init --agent-guidance add";
+var _testOnly = {
+  toPortableRelativePath,
+  ensureTrailingNewline,
+  detectLineEnding,
+  findGuidanceBlockRange,
+  buildAgentGuidanceBlock,
+  upsertAgentGuidanceBlock,
+  resolveProjectRoot,
+  resolveTargetGuidancePath,
+  parsePromptChoice,
+  pushUnique,
+  promptForGuidanceWrite,
+  normalizeAgentGuidanceState,
+  applyAgentGuidanceState,
+  writeGuidanceFile,
+  setAgentGuidanceReadlineFactoryForTests
+};
 var createAgentGuidanceReadlineInterface = () => readline.createInterface({ input, output });
+function setAgentGuidanceReadlineFactoryForTests(factory) {
+  createAgentGuidanceReadlineInterface = factory ?? (() => readline.createInterface({ input, output }));
+}
 function toPortableRelativePath(projectRoot, targetPath) {
-  const relative = path8.relative(projectRoot, targetPath);
+  const relative = path10.relative(projectRoot, targetPath);
   if (relative.length === 0) {
-    return path8.basename(targetPath);
+    return path10.basename(targetPath);
   }
-  return relative.split(path8.sep).join("/");
+  return relative.split(path10.sep).join("/");
 }
 function ensureTrailingNewline(value) {
   return value.endsWith("\n") ? value : `${value}
@@ -6076,14 +6374,14 @@ function upsertAgentGuidanceBlock(existingContent) {
   };
 }
 function resolveProjectRoot(pmRoot, cwd) {
-  const parent = path8.dirname(pmRoot);
-  if (path8.basename(pmRoot) === "pm" && path8.basename(parent) === ".agents") {
-    return path8.dirname(parent);
+  const parent = path10.dirname(pmRoot);
+  if (path10.basename(pmRoot) === "pm" && path10.basename(parent) === ".agents") {
+    return path10.dirname(parent);
   }
-  return path8.resolve(cwd, pmRoot);
+  return path10.resolve(cwd, pmRoot);
 }
 function resolveTargetGuidancePath(scans, projectRoot) {
-  const existingAgents = scans.find((entry) => path8.basename(entry.file_path) === "AGENTS.md" && entry.exists);
+  const existingAgents = scans.find((entry) => path10.basename(entry.file_path) === "AGENTS.md" && entry.exists);
   if (existingAgents) {
     return existingAgents.file_path;
   }
@@ -6091,7 +6389,7 @@ function resolveTargetGuidancePath(scans, projectRoot) {
   if (existingAny) {
     return existingAny.file_path;
   }
-  return path8.join(projectRoot, "AGENTS.md");
+  return path10.join(projectRoot, "AGENTS.md");
 }
 function parsePromptChoice(answer, currentDefault) {
   const normalized = answer.trim().toLowerCase();
@@ -6133,7 +6431,7 @@ function normalizeAgentGuidanceState(settings) {
 async function scanGuidanceFiles(projectRoot) {
   const scans = [];
   for (const filename of AGENT_GUIDANCE_TARGET_FILENAMES) {
-    const filePath = path8.join(projectRoot, filename);
+    const filePath = path10.join(projectRoot, filename);
     const exists = await pathExists(filePath);
     if (!exists) {
       scans.push({
@@ -6144,7 +6442,7 @@ async function scanGuidanceFiles(projectRoot) {
       });
       continue;
     }
-    const content = await fs7.readFile(filePath, "utf8");
+    const content = await fs9.readFile(filePath, "utf8");
     const contentLower = content.toLowerCase();
     const tokenHits = AGENT_GUIDANCE_REQUIRED_TOKENS.filter((token) => contentLower.includes(token));
     const hasMarker = hasGuidanceMarker(content);
@@ -6172,12 +6470,12 @@ function applyAgentGuidanceState(settings, currentState) {
 }
 async function writeGuidanceFile(filePath) {
   const exists = await pathExists(filePath);
-  const currentContent = exists ? await fs7.readFile(filePath, "utf8") : "";
+  const currentContent = exists ? await fs9.readFile(filePath, "utf8") : "";
   const nextContent = upsertAgentGuidanceBlock(currentContent);
   if (!nextContent.changed) {
     return { changed: false, warnings: [] };
   }
-  await fs7.writeFile(filePath, nextContent.next_content, "utf8");
+  await writeFileAtomic(filePath, nextContent.next_content);
   return {
     changed: true,
     warnings: await runActiveOnWriteHooks({
@@ -6359,7 +6657,12 @@ async function runInitAgentGuidance(options) {
   };
 }
 
-// dist/cli/commands/init.js
+// dist/sdk/init.js
+import fs10 from "node:fs/promises";
+import path11 from "node:path";
+import readline2 from "node:readline/promises";
+import { stdin as input2, stdout as output2 } from "node:process";
+import { hostname, userInfo } from "node:os";
 function summarizeInitResult(result) {
   return {
     ok: result.ok,
@@ -6383,7 +6686,28 @@ function summarizeInitResult(result) {
     hint: "Re-run with --verbose for the full settings tree."
   };
 }
+var _testOnly2 = {
+  normalizeInitGovernancePreset,
+  normalizeInitTypePreset,
+  normalizeOptionalInitAuthor,
+  normalizeInitAgentGuidanceMode,
+  isPathLikeInitTarget,
+  resolveInitInvocation,
+  resolveInitPrefixInput,
+  parseYesNoChoice,
+  applyGovernancePreset,
+  runInitWizard,
+  setInitReadlineFactoryForTests,
+  summarizeInstalledPackages,
+  buildInitNextSteps,
+  registerInitTypePreset,
+  assertExplicitTrackerPathIsNotWorkspaceRoot,
+  isLikelyWorkspaceRoot
+};
 var createInitReadlineInterface = () => readline2.createInterface({ input: input2, output: output2 });
+function setInitReadlineFactoryForTests(factory) {
+  createInitReadlineInterface = factory ?? (() => readline2.createInterface({ input: input2, output: output2 }));
+}
 function cloneDefaults() {
   return structuredClone(SETTINGS_DEFAULTS);
 }
@@ -6439,7 +6763,7 @@ function isPathLikeInitTarget(rawValue) {
   if (trimmed.length === 0) {
     return false;
   }
-  return path9.isAbsolute(trimmed) || trimmed.startsWith(".") || trimmed.includes("/") || trimmed.includes("\\");
+  return path11.isAbsolute(trimmed) || /^[a-z]:/iu.test(trimmed) || trimmed.startsWith(".") || trimmed.includes("/") || trimmed.includes("\\");
 }
 function resolveInitInvocation(cwd, global, prefixArg, workspaceArg) {
   const normalizedWorkspace = workspaceArg?.trim();
@@ -6450,8 +6774,8 @@ function resolveInitInvocation(cwd, global, prefixArg, workspaceArg) {
     if (global.path !== void 0 || isPathLikeInitTarget(prefixArg)) {
       throw new PmCliError("--workspace cannot be combined with --pm-path/--path or a path-like positional target.", EXIT_CODE.USAGE);
     }
-    const workspaceRoot = path9.resolve(cwd, normalizedWorkspace);
-    const pmRoot2 = path9.join(workspaceRoot, ".agents", "pm");
+    const workspaceRoot = path11.resolve(cwd, normalizedWorkspace);
+    const pmRoot2 = path11.join(workspaceRoot, ".agents", "pm");
     return {
       pmRoot: pmRoot2,
       prefixArg,
@@ -6463,7 +6787,7 @@ function resolveInitInvocation(cwd, global, prefixArg, workspaceArg) {
     };
   }
   if (global.path === void 0 && isPathLikeInitTarget(prefixArg)) {
-    const positionalTarget = path9.resolve(cwd, prefixArg.trim());
+    const positionalTarget = path11.resolve(cwd, prefixArg.trim());
     return {
       pmRoot: positionalTarget,
       prefixArg: void 0,
@@ -6481,6 +6805,35 @@ function resolveInitInvocation(cwd, global, prefixArg, workspaceArg) {
     } : { mode: "tracker-path", tracker_root: pmRoot }
   };
 }
+function resolveInitPrefixInput(positionalPrefix, flaggedPrefix) {
+  if (flaggedPrefix === void 0) {
+    return positionalPrefix;
+  }
+  if (flaggedPrefix.trim().length === 0) {
+    throw new PmCliError("--id-prefix must not be empty", EXIT_CODE.USAGE);
+  }
+  if (isPathLikeInitTarget(flaggedPrefix)) {
+    throw new PmCliError(`--id-prefix accepts an item ID prefix, not a tracker path: "${flaggedPrefix}".`, EXIT_CODE.USAGE, {
+      code: "init_id_prefix_path_like",
+      required: "Pass the tracker path positionally or with the global --path option.",
+      examples: [
+        `pm init ${flaggedPrefix}`,
+        `pm --path ${flaggedPrefix} init`
+      ]
+    });
+  }
+  if (positionalPrefix !== void 0 && normalizePrefix(positionalPrefix) !== normalizePrefix(flaggedPrefix)) {
+    throw new PmCliError(`Conflicting id prefixes: positional "${positionalPrefix}" and --id-prefix "${flaggedPrefix}".`, EXIT_CODE.USAGE, {
+      code: "init_id_prefix_conflict",
+      required: "Use either the positional id prefix or --id-prefix with one value.",
+      examples: [
+        `pm init ${normalizePrefix(positionalPrefix)}`,
+        `pm init --id-prefix ${normalizePrefix(flaggedPrefix)}`
+      ]
+    });
+  }
+  return flaggedPrefix;
+}
 function normalizeInitAgentGuidanceMode(rawValue) {
   if (rawValue === void 0) {
     return "ask";
@@ -6556,10 +6909,10 @@ async function isLikelyWorkspaceRoot(candidate) {
     "package.json",
     "pnpm-workspace.yaml",
     "AGENTS.md",
-    path9.join(".agents", "pm")
+    path11.join(".agents", "pm")
   ];
   for (const indicator of indicators) {
-    if (await pathExists(path9.join(candidate, indicator))) {
+    if (await pathExists(path11.join(candidate, indicator))) {
       return true;
     }
   }
@@ -6569,13 +6922,13 @@ async function assertExplicitTrackerPathIsNotWorkspaceRoot(pmRoot, explicitTrack
   if (!explicitTrackerTarget || force) {
     return;
   }
-  if (await pathExists(path9.join(pmRoot, "settings.json"))) {
+  if (await pathExists(path11.join(pmRoot, "settings.json"))) {
     return;
   }
   if (!await isLikelyWorkspaceRoot(pmRoot)) {
     return;
   }
-  const nestedTracker = path9.join(pmRoot, ".agents", "pm");
+  const nestedTracker = path11.join(pmRoot, ".agents", "pm");
   throw new PmCliError(`Refusing to initialize tracker files directly in workspace root "${pmRoot}".`, EXIT_CODE.USAGE, {
     code: "workspace_root_pm_path",
     type: "urn:pm-cli:error:workspace_root_pm_path",
@@ -6599,9 +6952,9 @@ async function ensureInitDirectories(pmRoot, subdirs) {
   const createdDirs = [];
   const warnings = [];
   for (const subdir of subdirs) {
-    const target = subdir ? path9.join(pmRoot, subdir) : pmRoot;
+    const target = subdir ? path11.join(pmRoot, subdir) : pmRoot;
     const existed = await pathExists(target);
-    await fs8.mkdir(target, { recursive: true });
+    await fs10.mkdir(target, { recursive: true });
     if (existed) {
       warnings.push(`already_exists:${target}`);
     } else {
@@ -6758,9 +7111,8 @@ async function createNewInitSettings(params) {
   const settings = cloneDefaults();
   settings.id_prefix = normalizedPrefix;
   applyGovernancePreset(settings, effectivePreset);
-  if (params.normalizedOptions.authorFromOption !== void 0) {
-    settings.author_default = params.normalizedOptions.authorFromOption;
-  }
+  const environmentAuthor = process.env.PM_AUTHOR?.trim() || void 0;
+  settings.author_default = params.normalizedOptions.authorFromOption ?? environmentAuthor ?? `${userInfo().username}@${hostname()}`;
   if (chosenTelemetryEnabled !== void 0) {
     settings.telemetry.enabled = chosenTelemetryEnabled;
     settings.telemetry.first_run_prompt_completed = true;
@@ -6835,10 +7187,10 @@ async function ensureInitTypeDirectories(params) {
   params.warnings.push(...scaffold.warnings);
 }
 function resolveInitWorkspaceRoot(target) {
-  const trackerRoot = path9.resolve(target.tracker_root);
-  const agentsRoot = path9.dirname(trackerRoot);
-  if (path9.basename(trackerRoot) === "pm" && path9.basename(agentsRoot) === ".agents") {
-    return path9.dirname(agentsRoot);
+  const trackerRoot = path11.resolve(target.tracker_root);
+  const agentsRoot = path11.dirname(trackerRoot);
+  if (path11.basename(trackerRoot) === "pm" && path11.basename(agentsRoot) === ".agents") {
+    return path11.dirname(agentsRoot);
   }
   return target.workspace_root;
 }
@@ -6887,16 +7239,16 @@ async function runInit(prefixArg, global, options = {}) {
   const cwd = process.cwd();
   const invocation = resolveInitInvocation(cwd, global, prefixArg, options.workspace);
   const pmRoot = invocation.pmRoot;
-  prefixArg = invocation.prefixArg;
+  prefixArg = resolveInitPrefixInput(invocation.prefixArg, options.idPrefix);
+  const normalizedOptions = normalizeInitCommandOptions(options);
   await assertExplicitTrackerPathIsNotWorkspaceRoot(pmRoot, invocation.target.mode === "tracker-path", options.force === true);
   const createdDirs = [];
   const warnings = [];
   const baseDirs = await ensureInitDirectories(pmRoot, PM_REQUIRED_SUBDIRS);
   createdDirs.push(...baseDirs.createdDirs);
   warnings.push(...baseDirs.warnings);
-  const settingsPath = path9.join(pmRoot, "settings.json");
+  const settingsPath = path11.join(pmRoot, "settings.json");
   const settingsExists = await pathExists(settingsPath);
-  const normalizedOptions = normalizeInitCommandOptions(options);
   const settingsResolution = await resolveInitSettings({
     pmRoot,
     settingsPath,
@@ -6908,9 +7260,10 @@ async function runInit(prefixArg, global, options = {}) {
     warnings
   });
   let { settings } = settingsResolution;
+  const workspaceRoot = resolveInitWorkspaceRoot(invocation.target);
   const agentGuidance = await applyInitAgentGuidance({
     pmRoot,
-    cwd,
+    cwd: workspaceRoot ?? cwd,
     agentGuidanceMode: normalizedOptions.agentGuidanceMode,
     settings,
     warnings
@@ -6928,7 +7281,6 @@ async function runInit(prefixArg, global, options = {}) {
     settings = await readSettings(pmRoot);
   }
   await ensureInitTypeDirectories({ pmRoot, settings, createdDirs, warnings });
-  const workspaceRoot = resolveInitWorkspaceRoot(invocation.target);
   if (workspaceRoot) {
     const gitignore = await ensurePmGitignore(workspaceRoot);
     if (gitignore.changed) {
@@ -6974,9 +7326,13 @@ export {
   PM_GITIGNORE_END,
   getPmGitignoreBlock,
   ensurePmGitignore,
+  INIT_AGENT_GUIDANCE_MODE_VALUES,
+  _testOnly,
+  runInitAgentGuidance,
   summarizeInitResult,
+  _testOnly2,
   runInit
 };
-//# sourceMappingURL=chunk-DVOLZJ3C.js.map
+//# sourceMappingURL=chunk-J6EY5V4N.js.map
 
-//# debugId=6800d243-3c57-59f4-8e55-c1613574d53e
+//# debugId=f34a834c-7c67-555c-a8b0-6c26e7d8c12a