opencode-plugin-flow 5.2.2 → 5.3.1

package/dist/cli.js

@@ -1,17 +1,1691 @@
 #!/usr/bin/env node
 
+// src/distribution/activation.ts
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import {
+  access,
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  rename,
+  rm,
+  writeFile
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+  resolve,
+  sep
+} from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/version.ts
+import { createRequire } from "node:module";
+function resolveFlowPluginVersion() {
+  try {
+    const require2 = createRequire(import.meta.url);
+    const manifest = require2("../package.json");
+    if (manifest.version)
+      return manifest.version;
+  } catch {}
+  return "0.0.0";
+}
+
+// src/distribution/activation.ts
+var FLOW_PACKAGE_NAME = "opencode-plugin-flow";
+var OWNED_WRAPPER_MARKER = "// @opencode-plugin-flow-owned-wrapper v1";
+var NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+var MAX_LOCAL_PLUGIN_BYTES = 1024 * 1024;
+var EXACT_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+var FLOW_NPM_SPECIFIER_PATTERN = /^opencode-plugin-flow(?:@(.+))?$/;
+var LOCAL_PLUGIN_EXTENSION_PATTERN = /\.(?:js|ts)$/i;
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function configuredHome(env) {
+  return env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
+}
+function normalizedInjectedRoot(path) {
+  return normalize(resolve(path));
+}
+function resolveEnvironmentPath(value, project) {
+  return normalize(isAbsolute(value) ? value : resolve(project, value));
+}
+function systemManagedConfigRoot(platform, env) {
+  if (platform === "darwin")
+    return "/Library/Application Support/opencode";
+  if (platform === "win32") {
+    return join(env.ProgramData?.trim() || "C:\\ProgramData", "opencode");
+  }
+  return "/etc/opencode";
+}
+function systemManagedPreferencePaths(platform, home) {
+  if (platform !== "darwin")
+    return [];
+  const username = basename(home) || "user";
+  return [
+    join("/Library/Managed Preferences", username, "ai.opencode.managed.plist"),
+    join("/Library/Managed Preferences", "ai.opencode.managed.plist")
+  ];
+}
+function isExactFlowVersion(value) {
+  return EXACT_VERSION_PATTERN.test(value);
+}
+function resolveActivationTarget(target) {
+  const resolved = target ?? resolveFlowPluginVersion();
+  if (!isExactFlowVersion(resolved)) {
+    throw new Error(`Flow activation target '${resolved}' must be an exact semantic version; tags and ranges are not resolved.`);
+  }
+  return resolved;
+}
+function resolveActivationPaths(project, options = {}) {
+  if (!isAbsolute(project)) {
+    throw new Error(`Flow activation project path must be absolute: ${project}`);
+  }
+  const env = options.env ?? process.env;
+  const home = normalizedInjectedRoot(options.home ?? configuredHome(env));
+  const configRoot = normalizedInjectedRoot(options.configRoot ?? (options.home ? join(home, ".config", "opencode") : env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, "opencode") : join(home, ".config", "opencode")));
+  const cacheRoot = normalizedInjectedRoot(options.cacheRoot ?? (options.home ? join(home, ".cache", "opencode") : env.XDG_CACHE_HOME ? join(env.XDG_CACHE_HOME, "opencode") : join(home, ".cache", "opencode")));
+  const absoluteProject = normalizedInjectedRoot(project);
+  const platform = options.platform ?? process.platform;
+  const customConfigFile = env.OPENCODE_CONFIG?.trim() ? resolveEnvironmentPath(env.OPENCODE_CONFIG.trim(), absoluteProject) : null;
+  const customConfigDirectory = env.OPENCODE_CONFIG_DIR?.trim() ? resolveEnvironmentPath(env.OPENCODE_CONFIG_DIR.trim(), absoluteProject) : null;
+  const managedConfigRoot = normalizedInjectedRoot(options.managedConfigRoot ?? env.OPENCODE_TEST_MANAGED_CONFIG_DIR ?? systemManagedConfigRoot(platform, env));
+  const globalConfigFiles = [
+    join(configRoot, "config.json"),
+    join(configRoot, "opencode.json"),
+    join(configRoot, "opencode.jsonc")
+  ];
+  const projectConfigFiles = [
+    join(absoluteProject, "opencode.jsonc"),
+    join(absoluteProject, "opencode.json")
+  ];
+  const projectDirectoryRoot = join(absoluteProject, ".opencode");
+  const projectDirectoryConfigFiles = [
+    join(projectDirectoryRoot, "opencode.json"),
+    join(projectDirectoryRoot, "opencode.jsonc")
+  ];
+  const customDirectoryConfigFiles = customConfigDirectory ? [
+    join(customConfigDirectory, "opencode.json"),
+    join(customConfigDirectory, "opencode.jsonc")
+  ] : [];
+  const managedConfigFiles = [
+    join(managedConfigRoot, "opencode.json"),
+    join(managedConfigRoot, "opencode.jsonc")
+  ];
+  const pluginDirectories = [
+    ...["plugin", "plugins"].map((name) => ({
+      source: "global-plugin-directory",
+      scope: "global",
+      path: join(configRoot, name),
+      safetyRoot: dirname(configRoot)
+    })),
+    ...["plugin", "plugins"].map((name) => ({
+      source: "home-plugin-directory",
+      scope: "global",
+      path: join(home, ".opencode", name),
+      safetyRoot: home
+    })),
+    ...["plugin", "plugins"].map((name) => ({
+      source: "project-plugin-directory",
+      scope: "project",
+      path: join(projectDirectoryRoot, name),
+      safetyRoot: absoluteProject
+    })),
+    ...customConfigDirectory ? ["plugin", "plugins"].map((name) => ({
+      source: "custom-plugin-directory",
+      scope: "custom",
+      path: join(customConfigDirectory, name),
+      safetyRoot: dirname(customConfigDirectory)
+    })) : []
+  ];
+  return {
+    project: absoluteProject,
+    home,
+    configRoot,
+    cacheRoot,
+    globalConfig: join(configRoot, "opencode.json"),
+    projectConfig: join(absoluteProject, "opencode.json"),
+    globalPluginDirectory: join(configRoot, "plugins"),
+    projectPluginDirectory: join(absoluteProject, ".opencode", "plugins"),
+    globalConfigFiles,
+    projectConfigFiles,
+    projectDirectoryConfigFiles,
+    customConfigFile,
+    customConfigDirectory,
+    customDirectoryConfigFiles,
+    managedConfigRoot,
+    managedConfigFiles,
+    pluginDirectories,
+    managedPreferencePaths: options.managedPreferencePaths?.map(normalizedInjectedRoot) ?? systemManagedPreferencePaths(platform, home),
+    hasInlineConfig: Boolean(env.OPENCODE_CONFIG_CONTENT?.trim()),
+    packageCacheRoot: join(cacheRoot, "packages"),
+    journalRoot: join(configRoot, "flow-activation-recovery"),
+    globalWrapperRecoveryRoot: join(configRoot, "flow-activation-recovery"),
+    projectWrapperRecoveryRoot: join(absoluteProject, ".opencode", "flow-activation-recovery"),
+    cacheRecoveryRoot: join(cacheRoot, "flow-activation-recovery")
+  };
+}
+async function optionalLstat(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return null;
+    throw error;
+  }
+}
+async function symlinkInPathRange(safetyRoot, target) {
+  const root = normalize(safetyRoot);
+  const destination = normalize(target);
+  const pathFromRoot = relative(root, destination);
+  if (pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)) {
+    throw new Error(`${destination} is outside its mutation safety root ${root}`);
+  }
+  let current = root;
+  const parts = pathFromRoot ? pathFromRoot.split(sep) : [];
+  for (let index = -1;index < parts.length; index += 1) {
+    if (index >= 0) {
+      const part = parts[index];
+      if (!part)
+        continue;
+      current = join(current, part);
+    }
+    const metadata = await optionalLstat(current);
+    if (!metadata)
+      return null;
+    if (metadata.isSymbolicLink())
+      return current;
+  }
+  return null;
+}
+async function assertSafeMutationPath(safetyRoot, target) {
+  const symlink = await symlinkInPathRange(safetyRoot, target);
+  if (symlink) {
+    throw new Error(`${target}: mutation refused because ancestor ${symlink} is a symbolic link`);
+  }
+}
+async function readRegularFileWithoutFollowing(path, maximumBytes) {
+  const pathMetadata = await lstat(path);
+  if (pathMetadata.isSymbolicLink()) {
+    throw new Error("symbolic link refused");
+  }
+  if (!pathMetadata.isFile())
+    throw new Error("not a regular file");
+  if (maximumBytes !== undefined && pathMetadata.size > maximumBytes) {
+    throw new Error(`file exceeds ${maximumBytes} bytes`);
+  }
+  const handle = await open(path, constants.O_RDONLY | NO_FOLLOW);
+  try {
+    const metadata = await handle.stat();
+    if (!metadata.isFile())
+      throw new Error("not a regular file");
+    if (metadata.dev !== pathMetadata.dev || metadata.ino !== pathMetadata.ino) {
+      throw new Error("file changed while activation was running");
+    }
+    return await handle.readFile({ encoding: "utf8" });
+  } catch (error) {
+    if (error.code === "ELOOP") {
+      throw new Error("symbolic link refused");
+    }
+    throw error;
+  } finally {
+    await handle.close();
+  }
+}
+function configDescriptors(paths) {
+  const descriptors = [
+    ...paths.globalConfigFiles.map((path) => ({
+      source: "global-config",
+      scope: "global",
+      path,
+      mutable: true,
+      safetyRoot: dirname(paths.configRoot),
+      manualRemediation: `edit ${path} manually`
+    })),
+    ...paths.customConfigFile ? [
+      {
+        source: "custom-config",
+        scope: "custom",
+        path: paths.customConfigFile,
+        mutable: true,
+        safetyRoot: dirname(paths.customConfigFile),
+        manualRemediation: `edit OPENCODE_CONFIG file ${paths.customConfigFile} manually`
+      }
+    ] : [],
+    ...paths.projectConfigFiles.map((path) => ({
+      source: "project-config",
+      scope: "project",
+      path,
+      mutable: true,
+      safetyRoot: paths.project,
+      manualRemediation: `edit ${path} manually`
+    })),
+    ...paths.projectDirectoryConfigFiles.map((path) => ({
+      source: "project-directory-config",
+      scope: "project",
+      path,
+      mutable: true,
+      safetyRoot: paths.project,
+      manualRemediation: `edit ${path} manually`
+    })),
+    ...paths.customDirectoryConfigFiles.map((path) => ({
+      source: "custom-directory-config",
+      scope: "custom",
+      path,
+      mutable: true,
+      safetyRoot: dirname(paths.customConfigDirectory),
+      manualRemediation: `edit OPENCODE_CONFIG_DIR file ${path} manually`
+    })),
+    ...paths.managedConfigFiles.map((path) => ({
+      source: "managed-config",
+      scope: "managed",
+      path,
+      mutable: false,
+      safetyRoot: dirname(paths.managedConfigRoot),
+      manualRemediation: `ask the OpenCode administrator to remove the Flow entry from ${path}`
+    }))
+  ];
+  const unique = new Map;
+  for (const descriptor of descriptors) {
+    const previous = unique.get(descriptor.path);
+    if (!previous || !descriptor.mutable && previous.mutable) {
+      unique.set(descriptor.path, descriptor);
+    }
+  }
+  return [...unique.values()];
+}
+function pluginDirectoryDescriptors(paths) {
+  const unique = new Map;
+  for (const descriptor of paths.pluginDirectories) {
+    if (!unique.has(descriptor.path))
+      unique.set(descriptor.path, descriptor);
+  }
+  return [...unique.values()];
+}
+function parseFlowNpmSpecifier(specifier) {
+  const match = FLOW_NPM_SPECIFIER_PATTERN.exec(specifier);
+  if (!match)
+    return { isFlow: false, version: null };
+  const candidate = match[1];
+  return {
+    isFlow: true,
+    version: candidate && isExactFlowVersion(candidate) ? candidate : null
+  };
+}
+function pluginSpecifier(entry) {
+  return Array.isArray(entry) ? entry[0] : entry;
+}
+function isPluginOptions(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parsePluginSpecs(value) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value)) {
+    throw new Error("config plugin must be an array");
+  }
+  return value.map((entry, index) => {
+    if (typeof entry === "string")
+      return entry;
+    if (Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && isPluginOptions(entry[1])) {
+      return [entry[0], entry[1]];
+    }
+    throw new Error(`config plugin[${index}] must be a string or [specifier, options] tuple`);
+  });
+}
+function stripJsoncComments(content) {
+  let output = "";
+  let inString = false;
+  let escaped = false;
+  for (let index = 0;index < content.length; index += 1) {
+    const character = content[index];
+    if (!character)
+      continue;
+    if (inString) {
+      output += character;
+      if (escaped)
+        escaped = false;
+      else if (character === "\\")
+        escaped = true;
+      else if (character === '"')
+        inString = false;
+      continue;
+    }
+    if (character === '"') {
+      inString = true;
+      output += character;
+      continue;
+    }
+    const next = content[index + 1];
+    if (character === "/" && next === "/") {
+      output += "  ";
+      index += 2;
+      while (index < content.length) {
+        const commentCharacter = content[index];
+        if (commentCharacter === `
+` || commentCharacter === "\r") {
+          index -= 1;
+          break;
+        }
+        output += " ";
+        index += 1;
+      }
+      continue;
+    }
+    if (character === "/" && next === "*") {
+      output += "  ";
+      index += 2;
+      let closed = false;
+      while (index < content.length) {
+        const commentCharacter = content[index];
+        const following = content[index + 1];
+        if (commentCharacter === "*" && following === "/") {
+          output += "  ";
+          index += 1;
+          closed = true;
+          break;
+        }
+        output += commentCharacter === `
+` || commentCharacter === "\r" ? commentCharacter : " ";
+        index += 1;
+      }
+      if (!closed)
+        throw new Error("unterminated block comment");
+      continue;
+    }
+    output += character;
+  }
+  if (inString)
+    throw new Error("unterminated JSON string");
+  return output;
+}
+function removeJsoncTrailingCommas(content) {
+  let output = "";
+  let inString = false;
+  let escaped = false;
+  for (let index = 0;index < content.length; index += 1) {
+    const character = content[index];
+    if (!character)
+      continue;
+    if (inString) {
+      output += character;
+      if (escaped)
+        escaped = false;
+      else if (character === "\\")
+        escaped = true;
+      else if (character === '"')
+        inString = false;
+      continue;
+    }
+    if (character === '"') {
+      inString = true;
+      output += character;
+      continue;
+    }
+    if (character === ",") {
+      let lookahead = index + 1;
+      while (/\s/.test(content[lookahead] ?? ""))
+        lookahead += 1;
+      if (content[lookahead] === "}" || content[lookahead] === "]") {
+        output += " ";
+        continue;
+      }
+    }
+    output += character;
+  }
+  return output;
+}
+function parseConfigContent(content) {
+  let parsed;
+  let format = "strict-json";
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    format = "jsonc";
+    parsed = JSON.parse(removeJsoncTrailingCommas(stripJsoncComments(content)));
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("config root must be a JSON object");
+  }
+  const value = parsed;
+  return { value, plugin: parsePluginSpecs(value.plugin), format };
+}
+function looksLikeFlowPath(path) {
+  const name = basename(path);
+  return /opencode-plugin-flow/i.test(path) || /(?:^|[-_.])flow(?:[-_.].*)?(?:plugin|wrapper)|(?:plugin|wrapper).*flow/i.test(name);
+}
+function parseOwnedWrapper(content) {
+  if (!content.startsWith(OWNED_WRAPPER_MARKER)) {
+    return { kind: "not-owned" };
+  }
+  const firstNewline = content.indexOf(`
+`);
+  const secondNewline = content.indexOf(`
+`, firstNewline + 1);
+  const thirdNewline = content.indexOf(`
+`, secondNewline + 1);
+  if (firstNewline < 0 || secondNewline < 0 || thirdNewline < 0) {
+    return { kind: "invalid", reason: "owned wrapper marker is incomplete" };
+  }
+  const versionLine = content.slice(firstNewline + 1, secondNewline);
+  const hashLine = content.slice(secondNewline + 1, thirdNewline);
+  const version = /^\/\/ version=(.+)$/.exec(versionLine)?.[1];
+  const expectedHash = /^\/\/ body-sha256=([a-f0-9]{64})$/.exec(hashLine)?.[1];
+  if (!version || !isExactFlowVersion(version)) {
+    return { kind: "invalid", reason: "owned wrapper version is invalid" };
+  }
+  if (!expectedHash) {
+    return { kind: "invalid", reason: "owned wrapper hash is invalid" };
+  }
+  const body = content.slice(thirdNewline + 1);
+  if (sha256(body) !== expectedHash) {
+    return { kind: "invalid", reason: "owned wrapper was edited" };
+  }
+  if (!body.includes(`${FLOW_PACKAGE_NAME}@${version}`)) {
+    return {
+      kind: "invalid",
+      reason: "owned wrapper body does not reference its declared Flow version"
+    };
+  }
+  return { kind: "owned", version };
+}
+function hintedFlowVersion(content) {
+  const candidate = new RegExp(`${FLOW_PACKAGE_NAME.replaceAll("-", "\\-")}@([^/\\s"']+)`).exec(content)?.[1];
+  return candidate && isExactFlowVersion(candidate) ? candidate : null;
+}
+async function classifyLocalPlugin(path, source, scope, target, specifier) {
+  const metadata = await optionalLstat(path);
+  if (!metadata) {
+    if (!looksLikeFlowPath(specifier))
+      return null;
+    return {
+      source,
+      scope,
+      path,
+      specifier,
+      resolvedVersion: null,
+      ownership: "unknown-flow-like",
+      status: "refused",
+      reason: "referenced local plugin is absent"
+    };
+  }
+  if (metadata.isSymbolicLink()) {
+    if (!looksLikeFlowPath(specifier) && !looksLikeFlowPath(path))
+      return null;
+    return {
+      source,
+      scope,
+      path,
+      specifier,
+      resolvedVersion: null,
+      ownership: "unknown-flow-like",
+      status: "refused",
+      reason: "symbolic link refused"
+    };
+  }
+  if (!metadata.isFile()) {
+    if (!looksLikeFlowPath(specifier) && !looksLikeFlowPath(path))
+      return null;
+    return {
+      source,
+      scope,
+      path,
+      specifier,
+      resolvedVersion: null,
+      ownership: "unknown-flow-like",
+      status: "refused",
+      reason: "local plugin is not a regular file"
+    };
+  }
+  let content;
+  try {
+    content = await readRegularFileWithoutFollowing(path, MAX_LOCAL_PLUGIN_BYTES);
+  } catch (error) {
+    if (!looksLikeFlowPath(specifier) && !looksLikeFlowPath(path))
+      return null;
+    return {
+      source,
+      scope,
+      path,
+      specifier,
+      resolvedVersion: null,
+      ownership: "unknown-flow-like",
+      status: "refused",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+  const owned = parseOwnedWrapper(content);
+  if (owned.kind === "owned") {
+    return {
+      source,
+      scope,
+      path,
+      specifier,
+      resolvedVersion: owned.version,
+      ownership: "marker-owned-wrapper",
+      status: "conflict",
+      reason: owned.version === target ? "local wrapper duplicates the canonical npm activation source" : "local wrapper activates another Flow version"
+    };
+  }
+  const flowLike = looksLikeFlowPath(specifier) || looksLikeFlowPath(path) || content.includes(FLOW_PACKAGE_NAME) || content.includes(OWNED_WRAPPER_MARKER);
+  if (!flowLike)
+    return null;
+  return {
+    source,
+    scope,
+    path,
+    specifier,
+    resolvedVersion: hintedFlowVersion(content),
+    ownership: "unknown-flow-like",
+    status: "refused",
+    reason: owned.kind === "invalid" ? owned.reason : "Flow-like local plugin has no verifiable ownership marker"
+  };
+}
+function relativeLocalSpecifier(configPath, specifier) {
+  if (specifier.startsWith("file:"))
+    return fileURLToPath(specifier);
+  if (isAbsolute(specifier))
+    return normalize(specifier);
+  return resolve(dirname(configPath), specifier);
+}
+function isLocalPluginSpecifier(specifier) {
+  return specifier.startsWith(".") || specifier.startsWith("file:") || isAbsolute(specifier);
+}
+async function inspectConfig(descriptor, target) {
+  const records = [];
+  const issues = [];
+  const symlinkAncestor = await symlinkInPathRange(descriptor.safetyRoot, descriptor.path);
+  if (symlinkAncestor) {
+    issues.push({
+      source: descriptor.source,
+      path: descriptor.path,
+      code: "unsafe-symlink",
+      message: `config ancestor ${symlinkAncestor} is a symbolic link`
+    });
+    return { records, issues };
+  }
+  const metadata = await optionalLstat(descriptor.path);
+  if (!metadata)
+    return { records, issues };
+  if (metadata.isSymbolicLink() || !metadata.isFile()) {
+    issues.push({
+      source: descriptor.source,
+      path: descriptor.path,
+      code: "invalid-config",
+      message: metadata.isSymbolicLink() ? "config symbolic link refused" : "config is not a regular file"
+    });
+    return { records, issues };
+  }
+  let content;
+  try {
+    content = await readRegularFileWithoutFollowing(descriptor.path);
+  } catch (error) {
+    issues.push({
+      source: descriptor.source,
+      path: descriptor.path,
+      code: "invalid-config",
+      message: error instanceof Error ? error.message : String(error)
+    });
+    return { records, issues };
+  }
+  let parsed;
+  try {
+    parsed = parseConfigContent(content);
+  } catch (error) {
+    issues.push({
+      source: descriptor.source,
+      path: descriptor.path,
+      code: "invalid-config",
+      message: `config cannot be conservatively parsed as JSON/JSONC: ${error instanceof Error ? error.message : String(error)}`
+    });
+    return { records, issues };
+  }
+  for (const entry of parsed.plugin) {
+    const specifier = pluginSpecifier(entry);
+    const npm = parseFlowNpmSpecifier(specifier);
+    if (npm.isFlow) {
+      const record = {
+        source: descriptor.source,
+        scope: descriptor.scope,
+        path: descriptor.path,
+        specifier,
+        resolvedVersion: npm.version,
+        ownership: "flow-npm",
+        status: npm.version === target ? "target" : "conflict"
+      };
+      if (npm.version === null) {
+        record.reason = "Flow npm activation is not pinned to an exact version";
+      } else if (npm.version !== target) {
+        record.reason = "Flow npm activation targets another version";
+      }
+      records.push(record);
+      continue;
+    }
+    if (!looksLikeFlowPath(specifier) && !isLocalPluginSpecifier(specifier)) {
+      continue;
+    }
+    let localPath;
+    try {
+      localPath = relativeLocalSpecifier(descriptor.path, specifier);
+    } catch {
+      if (!looksLikeFlowPath(specifier))
+        continue;
+      records.push({
+        source: descriptor.source,
+        scope: descriptor.scope,
+        path: specifier,
+        specifier,
+        resolvedVersion: null,
+        ownership: "unknown-flow-like",
+        status: "refused",
+        reason: "local Flow-like plugin specifier is invalid"
+      });
+      continue;
+    }
+    const local = await classifyLocalPlugin(localPath, descriptor.source, descriptor.scope, target, specifier);
+    if (local)
+      records.push(local);
+  }
+  return { records, issues };
+}
+async function inspectInlineConfig(content, project, target) {
+  const records = [];
+  const issues = [];
+  let parsed;
+  try {
+    parsed = parseConfigContent(content);
+  } catch (error) {
+    issues.push({
+      source: "inline-config",
+      path: "env:OPENCODE_CONFIG_CONTENT",
+      code: "invalid-config",
+      message: `inline config cannot be conservatively parsed as JSON/JSONC: ${error instanceof Error ? error.message : String(error)}`
+    });
+    return { records, issues };
+  }
+  const virtualConfigPath = join(project, "opencode.inline.json");
+  for (const entry of parsed.plugin) {
+    const specifier = pluginSpecifier(entry);
+    const npm = parseFlowNpmSpecifier(specifier);
+    if (npm.isFlow) {
+      const record = {
+        source: "inline-config",
+        scope: "inline",
+        path: "env:OPENCODE_CONFIG_CONTENT",
+        specifier,
+        resolvedVersion: npm.version,
+        ownership: "flow-npm",
+        status: npm.version === target ? "target" : "conflict"
+      };
+      if (npm.version === null) {
+        record.reason = "Flow npm activation is not pinned to an exact version";
+      } else if (npm.version !== target) {
+        record.reason = "Flow npm activation targets another version";
+      }
+      records.push(record);
+      continue;
+    }
+    if (!looksLikeFlowPath(specifier) && !isLocalPluginSpecifier(specifier)) {
+      continue;
+    }
+    let localPath;
+    try {
+      localPath = relativeLocalSpecifier(virtualConfigPath, specifier);
+    } catch {
+      if (!looksLikeFlowPath(specifier))
+        continue;
+      records.push({
+        source: "inline-config",
+        scope: "inline",
+        path: "env:OPENCODE_CONFIG_CONTENT",
+        specifier,
+        resolvedVersion: null,
+        ownership: "unknown-flow-like",
+        status: "refused",
+        reason: "inline local Flow-like plugin specifier is invalid"
+      });
+      continue;
+    }
+    const local = await classifyLocalPlugin(localPath, "inline-config", "inline", target, specifier);
+    if (local)
+      records.push(local);
+  }
+  return { records, issues };
+}
+async function inspectPluginDirectory(descriptor, target) {
+  const records = [];
+  const issues = [];
+  const symlinkAncestor = await symlinkInPathRange(descriptor.safetyRoot, descriptor.path);
+  if (symlinkAncestor) {
+    issues.push({
+      source: descriptor.source,
+      path: descriptor.path,
+      code: "unsafe-symlink",
+      message: `plugin directory ancestor ${symlinkAncestor} is a symbolic link`
+    });
+    return { records, issues };
+  }
+  const metadata = await optionalLstat(descriptor.path);
+  if (!metadata)
+    return { records, issues };
+  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+    issues.push({
+      source: descriptor.source,
+      path: descriptor.path,
+      code: "invalid-plugin-directory",
+      message: metadata.isSymbolicLink() ? "plugin directory symbolic link refused" : "plugin directory is not a real directory"
+    });
+    return { records, issues };
+  }
+  const entries = await readdir(descriptor.path, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!LOCAL_PLUGIN_EXTENSION_PATTERN.test(entry.name))
+      continue;
+    const path = join(descriptor.path, entry.name);
+    const record = await classifyLocalPlugin(path, descriptor.source, descriptor.scope, target, path);
+    if (record)
+      records.push(record);
+  }
+  return { records, issues };
+}
+async function inspectCacheArtifact(path, specifier, target) {
+  const metadata = await optionalLstat(path);
+  if (!metadata?.isDirectory() || metadata.isSymbolicLink()) {
+    return {
+      path,
+      specifier,
+      resolvedVersion: null,
+      status: "ambiguous",
+      reason: "cache artifact is not a real directory"
+    };
+  }
+  const nodeModulesPath = join(path, "node_modules");
+  const packagePath = join(nodeModulesPath, FLOW_PACKAGE_NAME);
+  const manifestPath = join(packagePath, "package.json");
+  try {
+    for (const directory of [nodeModulesPath, packagePath]) {
+      const directoryMetadata = await lstat(directory);
+      if (directoryMetadata.isSymbolicLink() || !directoryMetadata.isDirectory()) {
+        throw new Error("nested package path is not a real directory");
+      }
+    }
+    const manifest = JSON.parse(await readRegularFileWithoutFollowing(manifestPath));
+    if (manifest.name !== FLOW_PACKAGE_NAME || typeof manifest.version !== "string" || !isExactFlowVersion(manifest.version)) {
+      throw new Error("nested package manifest does not prove a Flow version");
+    }
+    return {
+      path,
+      specifier,
+      resolvedVersion: manifest.version,
+      status: manifest.version === target ? "target" : "inactive"
+    };
+  } catch (error) {
+    return {
+      path,
+      specifier,
+      resolvedVersion: null,
+      status: "ambiguous",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function inspectCache(paths, target) {
+  const artifacts = [];
+  const issues = [];
+  const symlinkAncestor = await symlinkInPathRange(dirname(paths.cacheRoot), paths.packageCacheRoot);
+  if (symlinkAncestor) {
+    issues.push({
+      source: "cache",
+      path: paths.packageCacheRoot,
+      code: "unsafe-symlink",
+      message: `cache ancestor ${symlinkAncestor} is a symbolic link`
+    });
+    return { artifacts, issues };
+  }
+  const metadata = await optionalLstat(paths.packageCacheRoot);
+  if (!metadata)
+    return { artifacts, issues };
+  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+    issues.push({
+      source: "cache",
+      path: paths.packageCacheRoot,
+      code: "ambiguous-cache-artifact",
+      message: "OpenCode package cache root is not a real directory"
+    });
+    return { artifacts, issues };
+  }
+  for (const entry of await readdir(paths.packageCacheRoot, {
+    withFileTypes: true
+  })) {
+    if (entry.name !== FLOW_PACKAGE_NAME && !entry.name.startsWith(`${FLOW_PACKAGE_NAME}@`)) {
+      continue;
+    }
+    const artifact = await inspectCacheArtifact(join(paths.packageCacheRoot, entry.name), entry.name, target);
+    artifacts.push(artifact);
+    if (artifact.status === "ambiguous") {
+      issues.push({
+        source: "cache",
+        path: artifact.path,
+        code: "ambiguous-cache-artifact",
+        message: artifact.reason ?? "cache artifact does not prove a Flow version"
+      });
+    }
+  }
+  return { artifacts, issues };
+}
+async function activationLimitations(paths) {
+  const limitations = [
+    {
+      source: "remote-config",
+      coverage: "runtime-leadership",
+      blocking: false,
+      detail: "Authenticated .well-known and organization API configs cannot be inspected offline; Flow runtime leadership detects duplicate loaded versions and fails closed."
+    }
+  ];
+  if (paths.managedPreferencePaths.length > 0) {
+    const detected = [];
+    for (const path of paths.managedPreferencePaths) {
+      try {
+        if (await optionalLstat(path))
+          detected.push(path);
+      } catch {
+        detected.push(`${path} (unreadable)`);
+      }
+    }
+    limitations.push({
+      source: "managed-preferences",
+      coverage: "runtime-leadership",
+      blocking: false,
+      detail: detected.length > 0 ? `Detected managed preference source(s) ${detected.join(", ")}; plist/MDM plugin values are not decoded by this dependency-free preflight, and runtime leadership fails closed on duplicates.` : "macOS MDM preferences may add runtime config outside readable JSON/JSONC files; Flow runtime leadership fails closed on duplicate loaded versions."
+    });
+  }
+  return limitations;
+}
+function activationReasons(records, cacheArtifacts, issues, target) {
+  const reasons = issues.map((issue) => `${issue.path}: ${issue.message}`);
+  const targetPins = records.filter((record) => record.ownership === "flow-npm" && record.resolvedVersion === target && record.status === "target");
+  if (targetPins.length !== 1) {
+    reasons.push(`expected one exact ${FLOW_PACKAGE_NAME}@${target} activation, found ${targetPins.length}`);
+  }
+  if (records.length !== 1) {
+    reasons.push(`expected one Flow activation source, found ${records.length}`);
+  }
+  const inactive = cacheArtifacts.filter((artifact) => artifact.status === "inactive");
+  if (inactive.length > 0) {
+    reasons.push(`found ${inactive.length} inactive Flow cache artifact(s)`);
+  }
+  return [...new Set(reasons)];
+}
+async function checkFlowActivation(options) {
+  const target = resolveActivationTarget(options.target);
+  const paths = resolveActivationPaths(options.project, options.paths);
+  const env = options.paths?.env ?? process.env;
+  const records = [];
+  const issues = [];
+  try {
+    const projectMetadata = await lstat(paths.project);
+    if (projectMetadata.isSymbolicLink()) {
+      issues.push({
+        source: "project",
+        path: paths.project,
+        code: "unsafe-symlink",
+        message: "project root symbolic link refused for activation mutation safety"
+      });
+    } else if (!projectMetadata.isDirectory()) {
+      issues.push({
+        source: "project",
+        path: paths.project,
+        code: "invalid-project",
+        message: "project path is not a directory"
+      });
+    }
+  } catch (error) {
+    issues.push({
+      source: "project",
+      path: paths.project,
+      code: "invalid-project",
+      message: error.code === "ENOENT" ? "project path does not exist" : error instanceof Error ? error.message : String(error)
+    });
+  }
+  for (const descriptor of configDescriptors(paths)) {
+    try {
+      const inspected = await inspectConfig(descriptor, target);
+      records.push(...inspected.records);
+      issues.push(...inspected.issues);
+    } catch (error) {
+      issues.push({
+        source: descriptor.source,
+        path: descriptor.path,
+        code: "invalid-config",
+        message: `config could not be inspected safely: ${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+  }
+  if (env.OPENCODE_CONFIG_CONTENT?.trim()) {
+    const inspected = await inspectInlineConfig(env.OPENCODE_CONFIG_CONTENT, paths.project, target);
+    records.push(...inspected.records);
+    issues.push(...inspected.issues);
+  }
+  for (const descriptor of pluginDirectoryDescriptors(paths)) {
+    try {
+      const inspected = await inspectPluginDirectory(descriptor, target);
+      records.push(...inspected.records);
+      issues.push(...inspected.issues);
+    } catch (error) {
+      issues.push({
+        source: descriptor.source,
+        path: descriptor.path,
+        code: "invalid-plugin-directory",
+        message: `plugin directory could not be inspected safely: ${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+  }
+  let cache;
+  try {
+    cache = await inspectCache(paths, target);
+  } catch (error) {
+    cache = {
+      artifacts: [],
+      issues: [
+        {
+          source: "cache",
+          path: paths.packageCacheRoot,
+          code: "ambiguous-cache-artifact",
+          message: `package cache could not be inspected safely: ${error instanceof Error ? error.message : String(error)}`
+        }
+      ]
+    };
+  }
+  issues.push(...cache.issues);
+  const limitations = await activationLimitations(paths);
+  const reasons = activationReasons(records, cache.artifacts, issues, target);
+  return {
+    mode: "check",
+    project: paths.project,
+    target,
+    paths,
+    records,
+    cacheArtifacts: cache.artifacts,
+    issues,
+    limitations,
+    singleVersionSatisfied: reasons.length === 0,
+    reasons
+  };
+}
+function detectIndent(content) {
+  return /\n([ \t]+)"/.exec(content)?.[1] ?? "\t";
+}
+async function readConfigSnapshot(descriptor) {
+  const metadata = await optionalLstat(descriptor.path);
+  if (!metadata) {
+    return {
+      descriptor,
+      exists: false,
+      content: null,
+      digest: null,
+      value: {},
+      plugin: [],
+      format: "strict-json",
+      indent: "\t",
+      newline: `
+`,
+      finalNewline: true,
+      mode: 384
+    };
+  }
+  if (metadata.isSymbolicLink() || !metadata.isFile()) {
+    throw new Error(`${descriptor.path}: config must be a regular file`);
+  }
+  await assertSafeMutationPath(descriptor.safetyRoot, descriptor.path);
+  const content = await readRegularFileWithoutFollowing(descriptor.path);
+  let parsed;
+  try {
+    parsed = parseConfigContent(content);
+  } catch (error) {
+    throw new Error(`${descriptor.path}: config cannot be conservatively parsed as JSON/JSONC: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return {
+    descriptor,
+    exists: true,
+    content,
+    digest: sha256(content),
+    value: parsed.value,
+    plugin: parsed.plugin,
+    format: parsed.format,
+    indent: detectIndent(content),
+    newline: content.includes(`\r
+`) ? `\r
+` : `
+`,
+    finalNewline: content.endsWith(`
+`),
+    mode: metadata.mode & 511
+  };
+}
+function updatedConfigContent(snapshot, entries) {
+  const value = { ...snapshot.value, plugin: entries };
+  let content = JSON.stringify(value, null, snapshot.indent).replaceAll(`
+`, snapshot.newline);
+  if (snapshot.finalNewline)
+    content += snapshot.newline;
+  return content;
+}
+function wrapperRecoveryRoot(paths, wrapper) {
+  if ([
+    "global-config",
+    "project-config",
+    "project-directory-config",
+    "custom-config",
+    "custom-directory-config"
+  ].includes(wrapper.source)) {
+    return join(dirname(wrapper.path), ".flow-activation-recovery");
+  }
+  if (wrapper.source === "home-plugin-directory") {
+    return join(paths.home, ".opencode", "flow-activation-recovery");
+  }
+  if (wrapper.scope === "global")
+    return paths.globalWrapperRecoveryRoot;
+  if (wrapper.scope === "custom" && paths.customConfigDirectory) {
+    return join(paths.customConfigDirectory, "flow-activation-recovery");
+  }
+  return paths.projectWrapperRecoveryRoot;
+}
+function wrapperMutationSafetyRoot(paths, wrapper) {
+  const directory = pluginDirectoryDescriptors(paths).find((descriptor) => {
+    if (descriptor.source !== wrapper.source)
+      return false;
+    const fromDirectory = relative(descriptor.path, wrapper.path);
+    return fromDirectory !== ".." && !fromDirectory.startsWith(`..${sep}`) && !isAbsolute(fromDirectory);
+  });
+  if (directory)
+    return directory.safetyRoot;
+  const config = configDescriptors(paths).find((descriptor) => descriptor.source === wrapper.source);
+  return config?.safetyRoot ?? dirname(wrapper.path);
+}
+function uniqueOwnedWrappers(records) {
+  const wrappers = new Map;
+  for (const record of records) {
+    if (record.ownership !== "marker-owned-wrapper" || record.resolvedVersion === null) {
+      continue;
+    }
+    wrappers.set(record.path, {
+      path: record.path,
+      scope: record.scope,
+      source: record.source,
+      version: record.resolvedVersion
+    });
+  }
+  return [...wrappers.values()];
+}
+function removableConfigEntry(entry, descriptor, records) {
+  const specifier = pluginSpecifier(entry);
+  if (parseFlowNpmSpecifier(specifier).isFlow)
+    return true;
+  if (!isLocalPluginSpecifier(specifier) && !looksLikeFlowPath(specifier)) {
+    return false;
+  }
+  let localPath;
+  try {
+    localPath = relativeLocalSpecifier(descriptor.path, specifier);
+  } catch {
+    return false;
+  }
+  return records.some((record) => record.source === descriptor.source && record.specifier === specifier && record.path === localPath && record.ownership === "marker-owned-wrapper");
+}
+function activationRefusals(before) {
+  return [
+    ...before.issues.map((issue) => `${issue.path}: ${issue.message}`),
+    ...before.records.filter((record) => record.ownership === "unknown-flow-like").map((record) => `${record.path}: ${record.reason ?? "unknown Flow-like activation refused"}`),
+    ...before.cacheArtifacts.filter((artifact) => artifact.status === "ambiguous").map((artifact) => `${artifact.path}: ${artifact.reason ?? "ambiguous cache artifact refused"}`)
+  ];
+}
+async function assertUnchangedConfig(snapshot) {
+  await assertSafeMutationPath(snapshot.descriptor.safetyRoot, snapshot.descriptor.path);
+  const metadata = await optionalLstat(snapshot.descriptor.path);
+  if (!snapshot.exists) {
+    if (metadata) {
+      throw new Error(`${snapshot.descriptor.path}: config appeared while activation was running`);
+    }
+    return;
+  }
+  if (!metadata?.isFile() || metadata.isSymbolicLink()) {
+    throw new Error(`${snapshot.descriptor.path}: config changed while activation was running`);
+  }
+  const current = await readRegularFileWithoutFollowing(snapshot.descriptor.path);
+  if (sha256(current) !== snapshot.digest) {
+    throw new Error(`${snapshot.descriptor.path}: config changed while activation was running`);
+  }
+}
+async function atomicWriteConfig(snapshot, content, runId) {
+  await assertUnchangedConfig(snapshot);
+  await mkdir(dirname(snapshot.descriptor.path), { recursive: true });
+  await assertSafeMutationPath(snapshot.descriptor.safetyRoot, snapshot.descriptor.path);
+  const temporaryPath = join(dirname(snapshot.descriptor.path), `.${basename(snapshot.descriptor.path)}.flow-${runId}.tmp`);
+  try {
+    await writeFile(temporaryPath, content, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: snapshot.mode
+    });
+    await rename(temporaryPath, snapshot.descriptor.path);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+}
+async function configIsWritable(snapshot) {
+  if (!snapshot.descriptor.mutable)
+    return false;
+  try {
+    await assertSafeMutationPath(snapshot.descriptor.safetyRoot, snapshot.descriptor.path);
+    if (snapshot.exists) {
+      await access(snapshot.descriptor.path, constants.W_OK);
+      return true;
+    }
+    let parent = dirname(snapshot.descriptor.path);
+    while (!await optionalLstat(parent)) {
+      const next = dirname(parent);
+      if (next === parent)
+        return false;
+      parent = next;
+    }
+    await access(parent, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function pathCanBeMoved(source, destinationRoot) {
+  try {
+    await access(dirname(source), constants.W_OK);
+    let parent = destinationRoot;
+    while (!await optionalLstat(parent)) {
+      const next = dirname(parent);
+      if (next === parent)
+        return false;
+      parent = next;
+    }
+    await access(parent, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeJournal(journalPath, journal) {
+  await mkdir(dirname(journalPath), { recursive: true, mode: 448 });
+  const temporaryPath = `${journalPath}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(journal, null, 2)}
+`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 384
+    });
+    await rename(temporaryPath, journalPath);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+}
+async function verifyOwnedWrapper(wrapper) {
+  const content = await readRegularFileWithoutFollowing(wrapper.path, MAX_LOCAL_PLUGIN_BYTES);
+  const parsed = parseOwnedWrapper(content);
+  if (parsed.kind !== "owned" || parsed.version !== wrapper.version) {
+    throw new Error(`${wrapper.path}: owned wrapper changed while activation was running`);
+  }
+}
+async function verifyCacheArtifact(artifact, target) {
+  const inspected = await inspectCacheArtifact(artifact.path, artifact.specifier, target);
+  if (inspected.status !== "inactive" || inspected.resolvedVersion !== artifact.resolvedVersion) {
+    throw new Error(`${artifact.path}: cache artifact changed while activation was running`);
+  }
+}
+async function replaceKnownConfigContent(options) {
+  await assertSafeMutationPath(options.snapshot.descriptor.safetyRoot, options.snapshot.descriptor.path);
+  const current = await readRegularFileWithoutFollowing(options.snapshot.descriptor.path);
+  if (sha256(current) !== options.expectedDigest) {
+    throw new Error(`${options.snapshot.descriptor.path}: automatic restore refused because the applied config changed`);
+  }
+  const temporaryPath = join(dirname(options.snapshot.descriptor.path), `.${basename(options.snapshot.descriptor.path)}.restore-${options.runId}.tmp`);
+  try {
+    await writeFile(temporaryPath, options.content, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: options.mode
+    });
+    await rename(temporaryPath, options.snapshot.descriptor.path);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+}
+async function rollbackCompletedActions(options) {
+  const failures = [];
+  for (const action of options.journal.actions.toReversed()) {
+    if (action.state !== "complete")
+      continue;
+    try {
+      if (action.action === "rewrite-config") {
+        const snapshot = options.snapshots.find((candidate) => candidate.descriptor.path === action.path);
+        if (!snapshot || !action.appliedDigest) {
+          throw new Error("restore metadata is incomplete");
+        }
+        if (action.originalAbsent) {
+          await assertSafeMutationPath(snapshot.descriptor.safetyRoot, action.path);
+          const current = await readRegularFileWithoutFollowing(action.path);
+          if (sha256(current) !== action.appliedDigest) {
+            throw new Error("created config changed after apply; automatic removal refused");
+          }
+          if (!action.recoveryPath) {
+            throw new Error("created config recovery path is missing");
+          }
+          await assertSafeMutationPath(snapshot.descriptor.safetyRoot, action.recoveryPath);
+          await mkdir(dirname(action.recoveryPath), {
+            recursive: true,
+            mode: 448
+          });
+          await rename(action.path, action.recoveryPath);
+        } else {
+          if (!action.backupPath)
+            throw new Error("config backup is missing");
+          const backup = await readRegularFileWithoutFollowing(action.backupPath);
+          await replaceKnownConfigContent({
+            snapshot,
+            expectedDigest: action.appliedDigest,
+            content: backup,
+            mode: action.originalMode ?? snapshot.mode,
+            runId: options.runId
+          });
+        }
+      } else if (action.action === "quarantine-wrapper" || action.action === "quarantine-cache") {
+        if (!action.recoveryPath)
+          throw new Error("recovery path is missing");
+        let safetyRoot;
+        if (action.action === "quarantine-cache") {
+          safetyRoot = dirname(options.paths.cacheRoot);
+        } else {
+          const wrapper = options.wrappers.find((candidate) => candidate.path === action.path);
+          if (!wrapper)
+            throw new Error("wrapper safety metadata is missing");
+          safetyRoot = wrapperMutationSafetyRoot(options.paths, wrapper);
+        }
+        await assertSafeMutationPath(safetyRoot, action.path);
+        await assertSafeMutationPath(safetyRoot, action.recoveryPath);
+        if (await optionalLstat(action.path)) {
+          throw new Error("original path is occupied; automatic restore refused");
+        }
+        const recovery = await optionalLstat(action.recoveryPath);
+        if (!recovery || recovery.isSymbolicLink()) {
+          throw new Error("quarantined artifact is missing or symbolic");
+        }
+        await mkdir(dirname(action.path), { recursive: true });
+        await rename(action.recoveryPath, action.path);
+      }
+      action.state = "rolled-back";
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      action.state = "rollback-failed";
+      action.error = message;
+      failures.push(`${action.path}: ${message}`);
+    }
+    try {
+      await writeJournal(options.journalPath, options.journal);
+    } catch (error) {
+      failures.push(`journal update: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return failures;
+}
+async function applyFlowActivation(options) {
+  const target = resolveActivationTarget(options.target);
+  const before = await checkFlowActivation({
+    project: options.project,
+    target,
+    ...options.paths ? { paths: options.paths } : {}
+  });
+  const refusals = activationRefusals(before);
+  const snapshots = [];
+  for (const descriptor of configDescriptors(before.paths)) {
+    try {
+      snapshots.push(await readConfigSnapshot(descriptor));
+    } catch (error) {
+      refusals.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  const pin = `${FLOW_PACKAGE_NAME}@${target}`;
+  const canonicalPath = options.scope === "global" ? before.paths.globalConfig : before.paths.projectConfig;
+  const nextEntries = new Map;
+  for (const snapshot of snapshots) {
+    const retained = snapshot.plugin.filter((entry) => !removableConfigEntry(entry, snapshot.descriptor, before.records));
+    if (snapshot.descriptor.path === canonicalPath)
+      retained.push(pin);
+    nextEntries.set(snapshot.descriptor.path, retained);
+  }
+  const ownedWrappers = uniqueOwnedWrappers(before.records).filter((wrapper) => wrapper.source !== "inline-config" && wrapper.source !== "managed-config");
+  const wrappers = [];
+  for (const wrapper of ownedWrappers) {
+    try {
+      const safetyRoot = wrapperMutationSafetyRoot(before.paths, wrapper);
+      const recoveryRoot = wrapperRecoveryRoot(before.paths, wrapper);
+      await assertSafeMutationPath(safetyRoot, wrapper.path);
+      await assertSafeMutationPath(safetyRoot, recoveryRoot);
+      if (!await pathCanBeMoved(wrapper.path, recoveryRoot)) {
+        throw new Error(`${wrapper.path}: marker-owned wrapper or recovery parent is not writable; archive it manually and rerun activation-apply`);
+      }
+      wrappers.push(wrapper);
+    } catch (error) {
+      refusals.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  const provenInactiveCache = before.cacheArtifacts.filter((artifact) => artifact.status === "inactive");
+  const inactiveCache = [];
+  for (const artifact of provenInactiveCache) {
+    try {
+      const safetyRoot = dirname(before.paths.cacheRoot);
+      await assertSafeMutationPath(safetyRoot, artifact.path);
+      await assertSafeMutationPath(safetyRoot, before.paths.cacheRecoveryRoot);
+      if (!await pathCanBeMoved(artifact.path, before.paths.cacheRecoveryRoot)) {
+        throw new Error(`${artifact.path}: proven inactive cache artifact or recovery parent is not writable; move it outside ${before.paths.packageCacheRoot} manually and rerun activation-apply`);
+      }
+      inactiveCache.push(artifact);
+    } catch (error) {
+      refusals.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  const plan = [];
+  const changedSnapshots = [];
+  const addManualRemediation = (snapshot, path, detail) => {
+    plan.push({
+      action: "manual-remediation",
+      ...snapshot ? { scope: snapshot.descriptor.scope } : {},
+      path,
+      detail
+    });
+    refusals.push(`${path}: ${detail}`);
+  };
+  const scheduleConfigRewrite = async (snapshot, detail) => {
+    if (changedSnapshots.includes(snapshot))
+      return;
+    if (!snapshot.descriptor.mutable) {
+      addManualRemediation(snapshot, snapshot.descriptor.path, `managed config is immutable; ${snapshot.descriptor.manualRemediation}`);
+      return;
+    }
+    if (snapshot.format === "jsonc") {
+      addManualRemediation(snapshot, snapshot.descriptor.path, `JSONC Flow activation was inventoried but cannot be edited losslessly without a JSONC editor; ${snapshot.descriptor.manualRemediation}, remove every ${FLOW_PACKAGE_NAME} entry, then rerun activation-apply`);
+      return;
+    }
+    if (!await configIsWritable(snapshot)) {
+      addManualRemediation(snapshot, snapshot.descriptor.path, `config or its mutation path is not safely writable; ${snapshot.descriptor.manualRemediation}`);
+      return;
+    }
+    changedSnapshots.push(snapshot);
+    plan.push({
+      action: "rewrite-config",
+      scope: snapshot.descriptor.scope,
+      path: snapshot.descriptor.path,
+      detail
+    });
+  };
+  for (const snapshot of snapshots) {
+    const entries = nextEntries.get(snapshot.descriptor.path) ?? [];
+    const changed = snapshot.descriptor.path === canonicalPath && !snapshot.exists || JSON.stringify(entries) !== JSON.stringify(snapshot.plugin);
+    if (!changed)
+      continue;
+    await scheduleConfigRewrite(snapshot, snapshot.descriptor.path === canonicalPath ? `write canonical exact pin ${pin} last` : "remove recognized Flow activation entries while preserving string/tuple entries and options");
+  }
+  for (const record of before.records.filter((record2) => record2.source === "inline-config")) {
+    addManualRemediation(null, "env:OPENCODE_CONFIG_CONTENT", `inline Flow activation ${record.specifier} is immutable; remove it from OPENCODE_CONFIG_CONTENT or unset that variable, then rerun activation-apply`);
+  }
+  const canonicalSnapshot = snapshots.find((snapshot) => snapshot.descriptor.path === canonicalPath);
+  for (const wrapper of wrappers) {
+    plan.push({
+      action: "quarantine-wrapper",
+      scope: wrapper.scope,
+      path: wrapper.path,
+      detail: "move marker-proven wrapper outside OpenCode plugin discovery"
+    });
+  }
+  for (const artifact of inactiveCache) {
+    plan.push({
+      action: "quarantine-cache",
+      path: artifact.path,
+      detail: `move proven inactive Flow ${artifact.resolvedVersion} cache artifact; never clear the cache root`
+    });
+  }
+  const base = {
+    mode: options.apply === true ? "apply" : "dry-run",
+    project: before.project,
+    target,
+    scope: options.scope,
+    status: refusals.length > 0 ? "refused" : "ready",
+    before,
+    plan,
+    refusals: [...new Set(refusals)]
+  };
+  if (options.apply !== true || refusals.length > 0)
+    return base;
+  if (plan.length === 0) {
+    return { ...base, status: "applied", after: before };
+  }
+  const runId = `${new Date().toISOString().replaceAll(":", "-")}-${randomUUID()}`;
+  const runRoot = join(before.paths.journalRoot, runId);
+  const journalPath = join(runRoot, "journal.json");
+  const actions = [];
+  for (const snapshot of changedSnapshots) {
+    const action = {
+      action: "rewrite-config",
+      path: snapshot.descriptor.path,
+      originalAbsent: !snapshot.exists,
+      originalMode: snapshot.mode,
+      state: "pending"
+    };
+    if (snapshot.exists) {
+      action.backupPath = join(runRoot, "configs", `${snapshot.descriptor.source}-${sha256(snapshot.descriptor.path).slice(0, 12)}.backup`);
+    } else {
+      action.recoveryPath = join(dirname(snapshot.descriptor.path), ".flow-activation-recovery", runId, `${basename(snapshot.descriptor.path)}-${sha256(snapshot.descriptor.path).slice(0, 12)}`);
+    }
+    actions.push(action);
+  }
+  for (const wrapper of wrappers) {
+    actions.push({
+      action: "quarantine-wrapper",
+      path: wrapper.path,
+      recoveryPath: join(wrapperRecoveryRoot(before.paths, wrapper), runId, `${basename(wrapper.path)}-${sha256(wrapper.path).slice(0, 12)}`),
+      state: "pending"
+    });
+  }
+  for (const artifact of inactiveCache) {
+    actions.push({
+      action: "quarantine-cache",
+      path: artifact.path,
+      recoveryPath: join(before.paths.cacheRecoveryRoot, runId, `${basename(artifact.path)}-${sha256(artifact.path).slice(0, 12)}`),
+      state: "pending"
+    });
+  }
+  const journal = {
+    format: "flow-activation-journal-v1",
+    runId,
+    createdAt: new Date().toISOString(),
+    project: before.project,
+    target,
+    scope: options.scope,
+    state: "prepared",
+    actions
+  };
+  try {
+    await assertSafeMutationPath(dirname(before.paths.configRoot), runRoot);
+    await mkdir(runRoot, { recursive: true, mode: 448 });
+    await writeJournal(journalPath, journal);
+  } catch (error) {
+    const message = `recovery journal could not be prepared safely at ${journalPath}: ${error instanceof Error ? error.message : String(error)}`;
+    return {
+      ...base,
+      status: "refused",
+      refusals: [...new Set([...base.refusals, message])]
+    };
+  }
+  try {
+    for (const snapshot of changedSnapshots) {
+      await assertUnchangedConfig(snapshot);
+      const action = actions.find((candidate) => candidate.action === "rewrite-config" && candidate.path === snapshot.descriptor.path);
+      if (snapshot.exists && action?.backupPath) {
+        await mkdir(dirname(action.backupPath), {
+          recursive: true,
+          mode: 448
+        });
+        await writeFile(action.backupPath, snapshot.content, {
+          encoding: "utf8",
+          flag: "wx",
+          mode: 384
+        });
+      }
+    }
+    if (canonicalSnapshot && !changedSnapshots.includes(canonicalSnapshot)) {
+      await assertUnchangedConfig(canonicalSnapshot);
+    }
+    for (const wrapper of wrappers)
+      await verifyOwnedWrapper(wrapper);
+    for (const artifact of inactiveCache) {
+      await verifyCacheArtifact(artifact, target);
+    }
+    journal.state = "applying";
+    await writeJournal(journalPath, journal);
+    const nonTargetConfigs = changedSnapshots.filter((snapshot) => snapshot.descriptor.path !== canonicalPath);
+    const targetConfig = changedSnapshots.find((snapshot) => snapshot.descriptor.path === canonicalPath);
+    for (const snapshot of nonTargetConfigs) {
+      const entries = nextEntries.get(snapshot.descriptor.path) ?? [];
+      const content = updatedConfigContent(snapshot, entries);
+      await atomicWriteConfig(snapshot, content, runId);
+      const action = actions.find((candidate) => candidate.action === "rewrite-config" && candidate.path === snapshot.descriptor.path);
+      if (action) {
+        action.appliedDigest = sha256(content);
+        action.state = "complete";
+      }
+      await writeJournal(journalPath, journal);
+      await options.afterMutation?.(plan.find((operation) => operation.action === "rewrite-config" && operation.path === snapshot.descriptor.path));
+    }
+    for (const wrapper of wrappers) {
+      const action = actions.find((candidate) => candidate.action === "quarantine-wrapper" && candidate.path === wrapper.path);
+      if (!action?.recoveryPath) {
+        throw new Error(`${wrapper.path}: missing wrapper recovery path`);
+      }
+      await verifyOwnedWrapper(wrapper);
+      await assertSafeMutationPath(wrapperMutationSafetyRoot(before.paths, wrapper), wrapper.path);
+      await mkdir(dirname(action.recoveryPath), {
+        recursive: true,
+        mode: 448
+      });
+      await rename(wrapper.path, action.recoveryPath);
+      action.state = "complete";
+      await writeJournal(journalPath, journal);
+      await options.afterMutation?.(plan.find((operation) => operation.action === "quarantine-wrapper" && operation.path === wrapper.path));
+    }
+    for (const artifact of inactiveCache) {
+      const action = actions.find((candidate) => candidate.action === "quarantine-cache" && candidate.path === artifact.path);
+      if (!action?.recoveryPath) {
+        throw new Error(`${artifact.path}: missing cache recovery path`);
+      }
+      await verifyCacheArtifact(artifact, target);
+      await assertSafeMutationPath(dirname(before.paths.cacheRoot), artifact.path);
+      await mkdir(dirname(action.recoveryPath), {
+        recursive: true,
+        mode: 448
+      });
+      await rename(artifact.path, action.recoveryPath);
+      action.state = "complete";
+      await writeJournal(journalPath, journal);
+      await options.afterMutation?.(plan.find((operation) => operation.action === "quarantine-cache" && operation.path === artifact.path));
+    }
+    if (targetConfig) {
+      const targetEntries = nextEntries.get(targetConfig.descriptor.path) ?? [];
+      const targetContent = updatedConfigContent(targetConfig, targetEntries);
+      await atomicWriteConfig(targetConfig, targetContent, runId);
+      const targetAction = actions.find((candidate) => candidate.action === "rewrite-config" && candidate.path === targetConfig.descriptor.path);
+      if (targetAction) {
+        targetAction.appliedDigest = sha256(targetContent);
+        targetAction.state = "complete";
+      }
+      await writeJournal(journalPath, journal);
+      await options.afterMutation?.(plan.find((operation) => operation.action === "rewrite-config" && operation.path === targetConfig.descriptor.path));
+    }
+    const after = await checkFlowActivation({
+      project: before.project,
+      target,
+      ...options.paths ? { paths: options.paths } : {}
+    });
+    if (!after.singleVersionSatisfied) {
+      throw new Error(`post-apply inventory did not prove a single version: ${after.reasons.join("; ")}`);
+    }
+    journal.state = "complete";
+    await writeJournal(journalPath, journal);
+    return {
+      ...base,
+      status: "applied",
+      recovery: { runId, journalPath },
+      after,
+      refusals: []
+    };
+  } catch (error) {
+    journal.state = "failed";
+    journal.error = error instanceof Error ? error.message : String(error);
+    try {
+      await writeJournal(journalPath, journal);
+    } catch {}
+    const rollbackFailures = await rollbackCompletedActions({
+      journal,
+      journalPath,
+      runId,
+      snapshots: changedSnapshots,
+      paths: before.paths,
+      wrappers
+    });
+    const recoveryState = rollbackFailures.length === 0 ? "rolled-back" : "rollback-failed";
+    journal.state = recoveryState;
+    if (rollbackFailures.length > 0) {
+      journal.error = `${journal.error ?? "apply failed"}; rollback: ${rollbackFailures.join("; ")}`;
+    }
+    try {
+      await writeJournal(journalPath, journal);
+    } catch {}
+    const guidance = recoveryState === "rolled-back" ? [
+      "All completed mutations were restored from exact backups or quarantine renames.",
+      `Inspect ${journalPath} and resolve the recorded failure before retrying.`
+    ] : [
+      "Stop OpenCode before manual recovery.",
+      `Inspect ${journalPath}; for rollback-failed actions, restore backupPath to path or rename recoveryPath back to path only after verifying the destination is absent or unchanged.`,
+      "Do not delete the recovery directory until activation-check succeeds."
+    ];
+    return {
+      ...base,
+      status: "refused",
+      recovery: { runId, journalPath },
+      failure: {
+        message: journal.error ?? "activation apply failed",
+        recoveryState,
+        guidance
+      },
+      refusals: [journal.error ?? "activation apply failed"]
+    };
+  }
+}
+
 // src/distribution/legacy-cleanup.ts
-import { createHash } from "node:crypto";
-import { constants } from "node:fs";
+import { createHash as createHash2 } from "node:crypto";
+import { constants as constants2 } from "node:fs";
 import {
-  lstat,
-  mkdir,
-  open,
-  readdir,
-  rename
+  lstat as lstat2,
+  mkdir as mkdir2,
+  open as open2,
+  readdir as readdir2,
+  rename as rename2
 } from "node:fs/promises";
-import { homedir } from "node:os";
-import { isAbsolute, join, normalize, sep } from "node:path";
+import { homedir as homedir2 } from "node:os";
+import { isAbsolute as isAbsolute2, join as join2, normalize as normalize2, sep as sep2 } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 
 // src/guidance/ids.ts
@@ -28,52 +1702,52 @@ var FLOW_GUIDANCE_TOPICS = [
 
 // src/distribution/legacy-cleanup.ts
 var LEGACY_MARKER = ".flow-skill-version";
-var NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+var NO_FOLLOW2 = constants2.O_NOFOLLOW ?? 0;
 var SUPPORTED_LEGACY_MAJOR = "4";
 var POST_MOVE_VERIFICATION_ATTEMPTS = 4;
 var POST_MOVE_VERIFICATION_RETRY_MS = 25;
 var SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
-function configuredHome() {
-  return process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || homedir();
+function configuredHome2() {
+  return process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || homedir2();
 }
-function resolveLegacySkillsRoot(home = configuredHome()) {
-  return join(home, ".config", "opencode", "skills");
+function resolveLegacySkillsRoot(home = configuredHome2()) {
+  return join2(home, ".config", "opencode", "skills");
 }
-function resolveLegacyArchiveRoot(home = configuredHome()) {
-  return join(home, ".config", "opencode", "flow-legacy-skills");
+function resolveLegacyArchiveRoot(home = configuredHome2()) {
+  return join2(home, ".config", "opencode", "flow-legacy-skills");
 }
-function sha256(content) {
-  return createHash("sha256").update(content).digest("hex");
+function sha2562(content) {
+  return createHash2("sha256").update(content).digest("hex");
 }
 function safeLegacyPath(folder, relativePath) {
-  if (!relativePath || isAbsolute(relativePath) || relativePath.includes("\\") || relativePath.split("/").some((part) => !part || part === "." || part === "..")) {
+  if (!relativePath || isAbsolute2(relativePath) || relativePath.includes("\\") || relativePath.split("/").some((part) => !part || part === "." || part === "..")) {
     throw new Error(`unsafe marker path '${relativePath}'`);
   }
-  const resolved = normalize(join(folder, ...relativePath.split("/")));
-  if (!resolved.startsWith(`${folder}${sep}`)) {
+  const resolved = normalize2(join2(folder, ...relativePath.split("/")));
+  if (!resolved.startsWith(`${folder}${sep2}`)) {
     throw new Error(`unsafe marker path '${relativePath}'`);
   }
   return resolved;
 }
 async function optionalStat(path) {
   try {
-    return await lstat(path, { bigint: false });
+    return await lstat2(path, { bigint: false });
   } catch (error) {
     if (error.code === "ENOENT")
       return null;
     throw error;
   }
 }
-async function readRegularFileWithoutFollowing(path) {
+async function readRegularFileWithoutFollowing2(path) {
   let handle;
   try {
-    const pathMetadata = await lstat(path);
+    const pathMetadata = await lstat2(path);
     if (pathMetadata.isSymbolicLink()) {
       throw new Error(`symbolic link refused: ${path}`);
     }
     if (!pathMetadata.isFile())
       throw new Error(`not a regular file: ${path}`);
-    handle = await open(path, constants.O_RDONLY | NO_FOLLOW);
+    handle = await open2(path, constants2.O_RDONLY | NO_FOLLOW2);
     const metadata = await handle.stat();
     if (!metadata.isFile())
       throw new Error(`not a regular file: ${path}`);
@@ -169,8 +1843,8 @@ async function inspectLegacyFolder(name, folder) {
     };
   }
   try {
-    const markerPath = join(folder, LEGACY_MARKER);
-    const marker = parseMarker(await readRegularFileWithoutFollowing(markerPath));
+    const markerPath = join2(folder, LEGACY_MARKER);
+    const marker = parseMarker(await readRegularFileWithoutFollowing2(markerPath));
     assertSupportedLegacyVersion(marker.version);
     const directories = expectedDirectoryEntries(marker);
     for (const [relativeDirectory, expectedEntries] of directories) {
@@ -179,7 +1853,7 @@ async function inspectLegacyFolder(name, folder) {
       if (!directoryMetadata?.isDirectory()) {
         throw new Error(`expected real directory: ${relativeDirectory || "."}`);
       }
-      const actualEntries = await readdir(directory);
+      const actualEntries = await readdir2(directory);
       const unexpected = actualEntries.filter((entry) => !expectedEntries.has(entry));
       const missing = [...expectedEntries].filter((entry) => !actualEntries.includes(entry));
       if (unexpected.length > 0 || missing.length > 0) {
@@ -191,8 +1865,8 @@ async function inspectLegacyFolder(name, folder) {
     }
     for (const [relativePath, expectedHash] of marker.files) {
       const path = safeLegacyPath(folder, relativePath);
-      const content = await readRegularFileWithoutFollowing(path);
-      if (sha256(content) !== expectedHash) {
+      const content = await readRegularFileWithoutFollowing2(path);
+      if (sha2562(content) !== expectedHash) {
         throw new Error(`edited file refused: ${relativePath}`);
       }
     }
@@ -219,7 +1893,7 @@ async function ensureRealArchiveRoot(path) {
     return;
   }
   try {
-    await mkdir(path, { mode: 448 });
+    await mkdir2(path, { mode: 448 });
   } catch (error) {
     if (error.code !== "EEXIST")
       throw error;
@@ -238,14 +1912,14 @@ async function verifyMovedLegacyFolder(name, archivePath) {
   return verified;
 }
 async function cleanupLegacySkills(options) {
-  const home = options?.home ?? configuredHome();
+  const home = options?.home ?? configuredHome2();
   const root = resolveLegacySkillsRoot(home);
   const archiveRoot = resolveLegacyArchiveRoot(home);
   const apply = options?.apply === true;
   const results = [];
   let archiveReady = false;
   for (const name of FLOW_GUIDANCE_TOPICS) {
-    const path = join(root, name);
+    const path = join2(root, name);
     const inspected = await inspectLegacyFolder(name, path);
     if (!apply || inspected.status !== "eligible") {
       results.push(inspected);
@@ -255,9 +1929,9 @@ async function cleanupLegacySkills(options) {
       await ensureRealArchiveRoot(archiveRoot);
       archiveReady = true;
     }
-    const archivePath = join(archiveRoot, `${name}-${new Date().toISOString().replaceAll(":", "-")}-${crypto.randomUUID()}`);
+    const archivePath = join2(archiveRoot, `${name}-${new Date().toISOString().replaceAll(":", "-")}-${crypto.randomUUID()}`);
     try {
-      await rename(path, archivePath);
+      await rename2(path, archivePath);
     } catch (error) {
       if (error.code !== "ENOENT")
         throw error;
@@ -305,37 +1979,39 @@ async function cleanupLegacySkills(options) {
   };
 }
 
-// src/version.ts
-import { createRequire } from "node:module";
-function resolveFlowPluginVersion() {
-  try {
-    const require2 = createRequire(import.meta.url);
-    const manifest = require2("../package.json");
-    if (manifest.version)
-      return manifest.version;
-  } catch {}
-  return "0.0.0";
-}
-
 // src/cli.ts
 function usage() {
   return [
-    "usage: opencode-plugin-flow legacy-cleanup <--dry-run|--apply> [--json]",
+    "usage:",
+    "  opencode-plugin-flow activation-check --project <absolute-path> [--target <exact-version>] [--json]",
+    "  opencode-plugin-flow activation-apply --project <absolute-path> --scope <global|project> [--target <exact-version>] [--apply] [--json]",
+    "  opencode-plugin-flow legacy-cleanup <--dry-run|--apply> [--json]",
     "",
     "commands:",
+    "  activation-check    Inventory all OpenCode Flow activation sources and cache artifacts",
+    "  activation-apply    Plan a single-version activation; mutate only with --apply",
     "  legacy-cleanup      Inspect or archive marker-proven legacy global Flow skills",
     "",
-    "options:",
+    "activation options:",
+    "  --project <path>    Absolute project/worktree path whose sources are inventoried",
+    "  --scope <scope>     Config that receives the one canonical exact npm pin",
+    "  --target <version>  Exact version only; defaults to this package's embedded version",
+    "  --apply             Create backups/journal and apply the activation plan",
+    "                      Without --apply, activation-apply is read-only",
+    "",
+    "legacy cleanup options:",
     "  --dry-run           Report eligible folders without changing the filesystem",
     "  --apply             Move eligible folders to a recoverable archive outside skill discovery",
     "                      Cleanup never deletes legacy folders",
+    "",
+    "common options:",
     "  --json              Write the report as JSON",
     "  --help              Show this help",
     "  --version           Print the plugin version"
   ].join(`
 `);
 }
-function writeReport(report, json) {
+function writeLegacyReport(report, json) {
   if (json) {
     process.stdout.write(`${JSON.stringify(report, null, 2)}
 `);
@@ -360,38 +2036,223 @@ function writeReport(report, json) {
     }
   }
 }
-async function main(argv) {
-  const [command, ...flags] = argv.slice(2);
-  if (command === "--help" || command === "-h") {
+function writeActivationCheck(report, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`Flow activation check: ${report.singleVersionSatisfied ? "satisfied" : "not satisfied"}
+`);
+  process.stdout.write(`- project: ${report.project}
+`);
+  process.stdout.write(`- target: opencode-plugin-flow@${report.target}
+`);
+  process.stdout.write(`- activation sources: ${report.records.length}
+`);
+  for (const record of report.records) {
+    process.stdout.write(`  - ${record.source}: ${record.specifier} (${record.ownership}, ${record.status}, version=${record.resolvedVersion ?? "unresolved"})
+`);
+    if (record.reason)
+      process.stdout.write(`    reason: ${record.reason}
+`);
+  }
+  process.stdout.write(`- Flow cache artifacts: ${report.cacheArtifacts.length}
+`);
+  for (const artifact of report.cacheArtifacts) {
+    process.stdout.write(`  - ${artifact.specifier}: ${artifact.status} (version=${artifact.resolvedVersion ?? "unresolved"})
+`);
+    if (artifact.reason)
+      process.stdout.write(`    reason: ${artifact.reason}
+`);
+  }
+  for (const limitation of report.limitations) {
+    process.stdout.write(`- limitation (${limitation.coverage}): ${limitation.source}
+  ${limitation.detail}
+`);
+  }
+  for (const reason of report.reasons) {
+    process.stdout.write(`- blocked: ${reason}
+`);
+  }
+}
+function writeActivationApply(report, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`Flow activation ${report.mode}: ${report.status}
+`);
+  process.stdout.write(`- project: ${report.project}
+`);
+  process.stdout.write(`- canonical scope: ${report.scope}
+`);
+  process.stdout.write(`- target: opencode-plugin-flow@${report.target}
+`);
+  for (const operation of report.plan) {
+    process.stdout.write(`- ${operation.action}: ${operation.path}
+  ${operation.detail}
+`);
+  }
+  for (const refusal of report.refusals) {
+    process.stdout.write(`- refused: ${refusal}
+`);
+  }
+  if (report.recovery) {
+    process.stdout.write(`- recovery journal: ${report.recovery.journalPath}
+`);
+  }
+  if (report.failure) {
+    process.stdout.write(`- recovery state: ${report.failure.recoveryState}
+- failure: ${report.failure.message}
+`);
+    for (const guidance of report.failure.guidance) {
+      process.stdout.write(`  recovery: ${guidance}
+`);
+    }
+  }
+  if (report.mode === "dry-run" && report.status === "ready") {
+    process.stdout.write(`- no files changed; repeat with --apply to execute
+`);
+  }
+}
+function parseActivationFlags(flags) {
+  const parsed = {
+    apply: false,
+    json: false,
+    help: false
+  };
+  const seen = new Set;
+  for (let index = 0;index < flags.length; index += 1) {
+    const flag = flags[index];
+    if (!flag || seen.has(flag))
+      return null;
+    seen.add(flag);
+    if (flag === "--apply") {
+      parsed.apply = true;
+      continue;
+    }
+    if (flag === "--json") {
+      parsed.json = true;
+      continue;
+    }
+    if (flag === "--help" || flag === "-h") {
+      parsed.help = true;
+      continue;
+    }
+    if (!["--project", "--target", "--scope"].includes(flag))
+      return null;
+    const value = flags[index + 1];
+    if (!value || value.startsWith("--"))
+      return null;
+    index += 1;
+    if (flag === "--project")
+      parsed.project = value;
+    if (flag === "--target")
+      parsed.target = value;
+    if (flag === "--scope")
+      parsed.scope = value;
+  }
+  return parsed;
+}
+function activationScope(value) {
+  return value === "global" || value === "project" ? value : null;
+}
+async function runActivationCheck(flags) {
+  const parsed = parseActivationFlags(flags);
+  if (!parsed || parsed.apply || parsed.scope || !parsed.project && !parsed.help) {
+    process.stderr.write(`${usage()}
+`);
+    process.exitCode = 2;
+    return;
+  }
+  if (parsed.help) {
     process.stdout.write(`${usage()}
 `);
     return;
   }
-  if (command === "--version" || command === "-v") {
-    process.stdout.write(`${resolveFlowPluginVersion()}
+  const report = await checkFlowActivation({
+    project: parsed.project,
+    ...parsed.target ? { target: parsed.target } : {}
+  });
+  writeActivationCheck(report, parsed.json);
+  if (!report.singleVersionSatisfied)
+    process.exitCode = 1;
+}
+async function runActivationApply(flags) {
+  const parsed = parseActivationFlags(flags);
+  const scope = activationScope(parsed?.scope);
+  if (!parsed || !parsed.project && !parsed.help || !scope && !parsed.help) {
+    process.stderr.write(`${usage()}
+`);
+    process.exitCode = 2;
+    return;
+  }
+  if (parsed.help) {
+    process.stdout.write(`${usage()}
 `);
     return;
   }
+  const report = await applyFlowActivation({
+    project: parsed.project,
+    scope,
+    apply: parsed.apply,
+    ...parsed.target ? { target: parsed.target } : {}
+  });
+  writeActivationApply(report, parsed.json);
+  if (report.status === "refused")
+    process.exitCode = 1;
+}
+async function runLegacyCleanup(flags) {
   const knownFlags = new Set(["--dry-run", "--apply", "--json"]);
   const validFlags = flags.every((flag) => knownFlags.has(flag));
   const dryRun = flags.includes("--dry-run");
   const apply = flags.includes("--apply");
-  if (command !== "legacy-cleanup" || !validFlags || dryRun === apply) {
+  if (!validFlags || dryRun === apply) {
     process.stderr.write(`${usage()}
 `);
     process.exitCode = 2;
     return;
   }
   const report = await cleanupLegacySkills({ apply });
-  writeReport(report, flags.includes("--json"));
+  writeLegacyReport(report, flags.includes("--json"));
   if (apply && report.results.some((result) => ["refused", "quarantined"].includes(result.status))) {
     process.exitCode = 1;
   }
 }
+async function main(argv) {
+  const [command, ...flags] = argv.slice(2);
+  if (command === "--help" || command === "-h") {
+    process.stdout.write(`${usage()}
+`);
+    return;
+  }
+  if (command === "--version" || command === "-v") {
+    process.stdout.write(`${resolveFlowPluginVersion()}
+`);
+    return;
+  }
+  if (command === "activation-check") {
+    await runActivationCheck(flags);
+    return;
+  }
+  if (command === "activation-apply") {
+    await runActivationApply(flags);
+    return;
+  }
+  if (command === "legacy-cleanup") {
+    await runLegacyCleanup(flags);
+    return;
+  }
+  process.stderr.write(`${usage()}
+`);
+  process.exitCode = 2;
+}
 main(process.argv).catch((error) => {
   process.stderr.write(`${error instanceof Error ? error.message : String(error)}
 `);
   process.exitCode = 1;
 });
 
-//# debugId=87C725E49214F7FF64756E2164756E21
+//# debugId=963853A3888CECEA64756E2164756E21