opencode-plugin-flow 5.3.1 → 5.3.2

package/dist/cli.js

@@ -11,6 +11,7 @@ import {
   readdir,
   rename,
   rm,
+  rmdir,
   writeFile
 } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -26,6 +27,93 @@ import {
 } from "node:path";
 import { fileURLToPath } from "node:url";
 
+// src/platform/opencode/leadership.ts
+var REGISTRY_KIND = "opencode-plugin-flow.runtime-leadership";
+var MAX_VERSION_LENGTH = 256;
+var FLOW_LEADERSHIP_REGISTRY_SYMBOL = Symbol.for(REGISTRY_KIND);
+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 parseSemanticVersion(version) {
+  if (version.length === 0 || version.length > MAX_VERSION_LENGTH)
+    return null;
+  const match = SEMVER_PATTERN.exec(version);
+  const major = match?.[1];
+  const minor = match?.[2];
+  const patch = match?.[3];
+  if (major === undefined || minor === undefined || patch === undefined) {
+    return null;
+  }
+  const prereleaseText = match?.[4];
+  const prerelease = prereleaseText ? prereleaseText.split(".").map((identifier) => /^\d+$/.test(identifier) ? { kind: "numeric", value: BigInt(identifier) } : { kind: "text", value: identifier }) : null;
+  return {
+    major: BigInt(major),
+    minor: BigInt(minor),
+    patch: BigInt(patch),
+    prerelease
+  };
+}
+function compareBigInts(left, right) {
+  if (left < right)
+    return -1;
+  if (left > right)
+    return 1;
+  return 0;
+}
+function compareText(left, right) {
+  if (left < right)
+    return -1;
+  if (left > right)
+    return 1;
+  return 0;
+}
+function comparePrerelease(left, right) {
+  if (left === null && right === null)
+    return 0;
+  if (left === null)
+    return 1;
+  if (right === null)
+    return -1;
+  const length = Math.max(left.length, right.length);
+  for (let index = 0;index < length; index += 1) {
+    const leftIdentifier = left[index];
+    const rightIdentifier = right[index];
+    if (leftIdentifier === undefined)
+      return -1;
+    if (rightIdentifier === undefined)
+      return 1;
+    if (leftIdentifier.kind === "numeric" && rightIdentifier.kind === "numeric") {
+      const comparison2 = compareBigInts(leftIdentifier.value, rightIdentifier.value);
+      if (comparison2 !== 0)
+        return comparison2;
+      continue;
+    }
+    if (leftIdentifier.kind === "numeric")
+      return -1;
+    if (rightIdentifier.kind === "numeric")
+      return 1;
+    const comparison = compareText(leftIdentifier.value, rightIdentifier.value);
+    if (comparison !== 0)
+      return comparison;
+  }
+  return 0;
+}
+function compareSemanticVersions(left, right) {
+  const leftVersion = parseSemanticVersion(left);
+  const rightVersion = parseSemanticVersion(right);
+  if (!leftVersion || !rightVersion) {
+    throw new TypeError("Flow leadership versions must be valid exact semantic versions.");
+  }
+  for (const [leftPart, rightPart] of [
+    [leftVersion.major, rightVersion.major],
+    [leftVersion.minor, rightVersion.minor],
+    [leftVersion.patch, rightVersion.patch]
+  ]) {
+    const comparison = compareBigInts(leftPart, rightPart);
+    if (comparison !== 0)
+      return comparison;
+  }
+  return comparePrerelease(leftVersion.prerelease, rightVersion.prerelease);
+}
+
 // src/version.ts
 import { createRequire } from "node:module";
 function resolveFlowPluginVersion() {
@@ -182,6 +270,15 @@ async function optionalLstat(path) {
     throw error;
   }
 }
+async function removeEmptyDirectory(path) {
+  try {
+    await rmdir(path);
+  } catch (error) {
+    const code = error.code;
+    if (code !== "ENOENT" && code !== "ENOTEMPTY")
+      throw error;
+  }
+}
 async function symlinkInPathRange(safetyRoot, target) {
   const root = normalize(safetyRoot);
   const destination = normalize(target);
@@ -497,6 +594,31 @@ function parseOwnedWrapper(content) {
   }
   return { kind: "owned", version };
 }
+function legacyFlowWrapperContent(version) {
+  return [
+    "const flowPluginUrl = new URL(",
+    `  "../.cache/opencode/packages/${FLOW_PACKAGE_NAME}@${version}/node_modules/${FLOW_PACKAGE_NAME}/dist/index.js",`,
+    `  \`file://\${process.env.HOME}/\`,`,
+    ")",
+    "",
+    "export default async function flowPlugin(input, options) {",
+    '  process.env.BUN_BE_BUN = "1"',
+    "  const { default: plugin } = await import(flowPluginUrl.href)",
+    "  return plugin(input, options)",
+    "}",
+    ""
+  ].join(`
+`);
+}
+function parseLegacyFlowWrapper(path, content) {
+  const normalized = content.replaceAll(`\r
+`, `
+`);
+  const version = hintedFlowVersion(normalized);
+  if (!version || basename(path) !== `flow-${version}-wrapper.js`)
+    return null;
+  return normalized === legacyFlowWrapperContent(version) ? { version } : null;
+}
 function hintedFlowVersion(content) {
   const candidate = new RegExp(`${FLOW_PACKAGE_NAME.replaceAll("-", "\\-")}@([^/\\s"']+)`).exec(content)?.[1];
   return candidate && isExactFlowVersion(candidate) ? candidate : null;
@@ -575,6 +697,19 @@ async function classifyLocalPlugin(path, source, scope, target, specifier) {
       reason: owned.version === target ? "local wrapper duplicates the canonical npm activation source" : "local wrapper activates another Flow version"
     };
   }
+  const legacy = parseLegacyFlowWrapper(path, content);
+  if (legacy) {
+    return {
+      source,
+      scope,
+      path,
+      specifier,
+      resolvedVersion: legacy.version,
+      ownership: "legacy-flow-wrapper",
+      status: "conflict",
+      reason: "exact known legacy Flow wrapper must be removed"
+    };
+  }
   const flowLike = looksLikeFlowPath(specifier) || looksLikeFlowPath(path) || content.includes(FLOW_PACKAGE_NAME) || content.includes(OWNED_WRAPPER_MARKER);
   if (!flowLike)
     return null;
@@ -1005,12 +1140,18 @@ async function checkFlowActivation(options) {
     };
   }
   issues.push(...cache.issues);
+  issues.push(...await activationJournalIssues(paths, options.ignoreRecoveryRunId));
   const limitations = await activationLimitations(paths);
   const reasons = activationReasons(records, cache.artifacts, issues, target);
   return {
     mode: "check",
     project: paths.project,
     target,
+    coverage: {
+      globalSources: true,
+      selectedProject: paths.project,
+      otherProjectTrees: false
+    },
     paths,
     records,
     cacheArtifacts: cache.artifacts,
@@ -1113,14 +1254,15 @@ function wrapperMutationSafetyRoot(paths, wrapper) {
 function uniqueOwnedWrappers(records) {
   const wrappers = new Map;
   for (const record of records) {
-    if (record.ownership !== "marker-owned-wrapper" || record.resolvedVersion === null) {
+    if (record.ownership !== "marker-owned-wrapper" && record.ownership !== "legacy-flow-wrapper" || record.resolvedVersion === null) {
       continue;
     }
     wrappers.set(record.path, {
       path: record.path,
       scope: record.scope,
       source: record.source,
-      version: record.resolvedVersion
+      version: record.resolvedVersion,
+      ownership: record.ownership
     });
   }
   return [...wrappers.values()];
@@ -1138,7 +1280,7 @@ function removableConfigEntry(entry, descriptor, records) {
   } catch {
     return false;
   }
-  return records.some((record) => record.source === descriptor.source && record.specifier === specifier && record.path === localPath && record.ownership === "marker-owned-wrapper");
+  return records.some((record) => record.source === descriptor.source && record.specifier === specifier && record.path === localPath && (record.ownership === "marker-owned-wrapper" || record.ownership === "legacy-flow-wrapper"));
 }
 function activationRefusals(before) {
   return [
@@ -1147,6 +1289,18 @@ function activationRefusals(before) {
     ...before.cacheArtifacts.filter((artifact) => artifact.status === "ambiguous").map((artifact) => `${artifact.path}: ${artifact.reason ?? "ambiguous cache artifact refused"}`)
   ];
 }
+function downgradeRefusals(before) {
+  const newerVersions = new Set;
+  for (const version of [
+    ...before.records.map((record) => record.resolvedVersion),
+    ...before.cacheArtifacts.map((artifact) => artifact.resolvedVersion)
+  ]) {
+    if (version && compareSemanticVersions(version, before.target) > 0) {
+      newerVersions.add(version);
+    }
+  }
+  return [...newerVersions].sort((left, right) => compareSemanticVersions(right, left)).map((version) => `refusing to replace newer installed Flow ${version} with older target ${before.target}; run ${FLOW_PACKAGE_NAME}@latest instead`);
+}
 async function assertUnchangedConfig(snapshot) {
   await assertSafeMutationPath(snapshot.descriptor.safetyRoot, snapshot.descriptor.path);
   const metadata = await optionalLstat(snapshot.descriptor.path);
@@ -1233,11 +1387,153 @@ async function writeJournal(journalPath, journal) {
     await rm(temporaryPath, { force: true });
   }
 }
+var TERMINAL_JOURNAL_STATES = new Set([
+  "complete",
+  "rolled-back"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseActivationJournal(content, journalPath) {
+  let value;
+  try {
+    value = JSON.parse(content);
+  } catch (error) {
+    throw new Error(`${journalPath}: recovery journal is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isRecord(value) || typeof value.runId !== "string" || value.runId !== basename(dirname(journalPath)) || typeof value.state !== "string") {
+    throw new Error(`${journalPath}: recovery journal schema is invalid`);
+  }
+  if (value.format === "flow-activation-journal-v1") {
+    if (![
+      "prepared",
+      "applying",
+      "complete",
+      "failed",
+      "rolled-back",
+      "rollback-failed"
+    ].includes(value.state)) {
+      throw new Error(`${journalPath}: legacy recovery journal state is invalid`);
+    }
+    return value;
+  }
+  if (value.format !== "flow-activation-journal-v2" || typeof value.createdAt !== "string" || typeof value.project !== "string" || !isAbsolute(value.project) || typeof value.target !== "string" || !isExactFlowVersion(value.target) || value.scope !== "global" && value.scope !== "project" || ![
+    "prepared",
+    "applying",
+    "committed",
+    "complete",
+    "failed",
+    "cleanup-failed",
+    "rolled-back",
+    "rollback-failed"
+  ].includes(value.state) || !Array.isArray(value.actions)) {
+    throw new Error(`${journalPath}: recovery journal schema is invalid`);
+  }
+  for (const action of value.actions) {
+    if (!isRecord(action) || !["rewrite-config", "remove-wrapper", "remove-cache"].includes(String(action.action)) || typeof action.path !== "string" || !isAbsolute(action.path) || !["pending", "complete", "rolled-back", "rollback-failed"].includes(String(action.state))) {
+      throw new Error(`${journalPath}: recovery journal action is invalid`);
+    }
+  }
+  if (value.ownerPid !== undefined && (!Number.isSafeInteger(value.ownerPid) || Number(value.ownerPid) <= 0)) {
+    throw new Error(`${journalPath}: recovery journal owner pid is invalid`);
+  }
+  return value;
+}
+async function readActivationJournalEntries(paths) {
+  try {
+    await assertSafeMutationPath(dirname(paths.configRoot), paths.journalRoot);
+  } catch (error) {
+    return [
+      {
+        journalPath: paths.journalRoot,
+        error: error instanceof Error ? error.message : String(error)
+      }
+    ];
+  }
+  const rootMetadata = await optionalLstat(paths.journalRoot);
+  if (!rootMetadata)
+    return [];
+  if (rootMetadata.isSymbolicLink() || !rootMetadata.isDirectory()) {
+    return [
+      {
+        journalPath: paths.journalRoot,
+        error: `${paths.journalRoot}: recovery root is not a real directory`
+      }
+    ];
+  }
+  const entries = [];
+  for (const directory of await readdir(paths.journalRoot, {
+    withFileTypes: true
+  })) {
+    const runRoot = join(paths.journalRoot, directory.name);
+    const journalPath = join(runRoot, "journal.json");
+    if (directory.isSymbolicLink()) {
+      entries.push({
+        journalPath,
+        error: `${runRoot}: symbolic recovery directory refused`
+      });
+      continue;
+    }
+    if (!directory.isDirectory() || !await optionalLstat(journalPath)) {
+      continue;
+    }
+    try {
+      const content = await readRegularFileWithoutFollowing(journalPath, MAX_LOCAL_PLUGIN_BYTES);
+      entries.push({
+        journalPath,
+        journal: parseActivationJournal(content, journalPath)
+      });
+    } catch (error) {
+      entries.push({
+        journalPath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return entries.sort((left, right) => left.journalPath.localeCompare(right.journalPath));
+}
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+async function activationJournalIssues(paths, ignoreRunId) {
+  const issues = [];
+  for (const entry of await readActivationJournalEntries(paths)) {
+    if (entry.error) {
+      issues.push({
+        source: "recovery",
+        path: entry.journalPath,
+        code: "incomplete-recovery",
+        message: entry.error
+      });
+      continue;
+    }
+    const journal = entry.journal;
+    if (journal.runId === ignoreRunId || TERMINAL_JOURNAL_STATES.has(journal.state)) {
+      continue;
+    }
+    const activeOwner = journal.format === "flow-activation-journal-v2" && journal.ownerPid !== undefined && processIsAlive(journal.ownerPid);
+    issues.push({
+      source: "recovery",
+      path: entry.journalPath,
+      code: "incomplete-recovery",
+      message: activeOwner ? `activation recovery is still owned by running process ${journal.ownerPid}` : journal.format === "flow-activation-journal-v1" ? `legacy activation recovery is incomplete in state ${journal.state}; follow that journal's manual recovery guidance before installing` : journal.state === "rollback-failed" ? "activation rollback previously failed and requires the journal's manual recovery guidance" : `activation recovery is incomplete in state ${journal.state}; rerun install to reconcile it before evaluating success`
+    });
+  }
+  return issues;
+}
 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`);
+  const version = wrapper.ownership === "marker-owned-wrapper" ? (() => {
+    const parsed = parseOwnedWrapper(content);
+    return parsed.kind === "owned" ? parsed.version : null;
+  })() : parseLegacyFlowWrapper(wrapper.path, content)?.version;
+  if (version !== wrapper.version) {
+    throw new Error(`${wrapper.path}: removable wrapper changed while activation was running`);
   }
 }
 async function verifyCacheArtifact(artifact, target) {
@@ -1247,19 +1543,19 @@ async function verifyCacheArtifact(artifact, target) {
   }
 }
 async function replaceKnownConfigContent(options) {
-  await assertSafeMutationPath(options.snapshot.descriptor.safetyRoot, options.snapshot.descriptor.path);
-  const current = await readRegularFileWithoutFollowing(options.snapshot.descriptor.path);
+  await assertSafeMutationPath(options.descriptor.safetyRoot, options.descriptor.path);
+  const current = await readRegularFileWithoutFollowing(options.descriptor.path);
   if (sha256(current) !== options.expectedDigest) {
-    throw new Error(`${options.snapshot.descriptor.path}: automatic restore refused because the applied config changed`);
+    throw new Error(`${options.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`);
+  const temporaryPath = join(dirname(options.descriptor.path), `.${basename(options.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);
+    await rename(temporaryPath, options.descriptor.path);
   } finally {
     await rm(temporaryPath, { force: true });
   }
@@ -1295,18 +1591,18 @@ async function rollbackCompletedActions(options) {
             throw new Error("config backup is missing");
           const backup = await readRegularFileWithoutFollowing(action.backupPath);
           await replaceKnownConfigContent({
-            snapshot,
+            descriptor: snapshot.descriptor,
             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");
+      } else if (action.action === "remove-wrapper" || action.action === "remove-cache") {
+        if (!action.stagingPath)
+          throw new Error("staging path is missing");
         let safetyRoot;
-        if (action.action === "quarantine-cache") {
+        if (action.action === "remove-cache") {
           safetyRoot = dirname(options.paths.cacheRoot);
         } else {
           const wrapper = options.wrappers.find((candidate) => candidate.path === action.path);
@@ -1315,16 +1611,16 @@ async function rollbackCompletedActions(options) {
           safetyRoot = wrapperMutationSafetyRoot(options.paths, wrapper);
         }
         await assertSafeMutationPath(safetyRoot, action.path);
-        await assertSafeMutationPath(safetyRoot, action.recoveryPath);
+        await assertSafeMutationPath(safetyRoot, action.stagingPath);
         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");
+        const staged = await optionalLstat(action.stagingPath);
+        if (!staged || staged.isSymbolicLink()) {
+          throw new Error("staged artifact is missing or symbolic");
         }
         await mkdir(dirname(action.path), { recursive: true });
-        await rename(action.recoveryPath, action.path);
+        await rename(action.stagingPath, action.path);
       }
       action.state = "rolled-back";
     } catch (error) {
@@ -1341,14 +1637,264 @@ async function rollbackCompletedActions(options) {
   }
   return failures;
 }
+function journalConfigDescriptor(paths, action) {
+  const descriptor = configDescriptors(paths).find((candidate) => candidate.path === action.path && (action.source === undefined || candidate.source === action.source));
+  if (!descriptor) {
+    throw new Error(`${action.path}: journal config path is outside inventory`);
+  }
+  return descriptor;
+}
+function journalOwnedWrapper(paths, journal, action) {
+  if (action.ownership !== "marker-owned-wrapper" && action.ownership !== "legacy-flow-wrapper" || typeof action.resolvedVersion !== "string" || !isExactFlowVersion(action.resolvedVersion) || typeof action.source !== "string" || typeof action.scope !== "string") {
+    throw new Error(`${action.path}: wrapper recovery metadata is incomplete`);
+  }
+  const wrapper = {
+    path: action.path,
+    source: action.source,
+    scope: action.scope,
+    version: action.resolvedVersion,
+    ownership: action.ownership
+  };
+  const pluginDirectory = pluginDirectoryDescriptors(paths).find((descriptor) => descriptor.source === wrapper.source && descriptor.scope === wrapper.scope && dirname(wrapper.path) === descriptor.path);
+  const config = configDescriptors(paths).find((descriptor) => {
+    if (descriptor.source !== wrapper.source || descriptor.scope !== wrapper.scope) {
+      return false;
+    }
+    const fromRoot = relative(descriptor.safetyRoot, wrapper.path);
+    return fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+  });
+  const safetyRoot = pluginDirectory?.safetyRoot ?? config?.safetyRoot;
+  if (!safetyRoot) {
+    throw new Error(`${action.path}: wrapper path is outside inventory`);
+  }
+  const expectedStagingPath = join(wrapperRecoveryRoot(paths, wrapper), journal.runId, sha256(action.path).slice(0, 12), basename(action.path));
+  if (action.stagingPath !== expectedStagingPath) {
+    throw new Error(`${action.path}: wrapper staging path does not match journal`);
+  }
+  return { wrapper, safetyRoot };
+}
+function journalCacheArtifact(paths, journal, action) {
+  if (typeof action.specifier !== "string" || action.specifier !== FLOW_PACKAGE_NAME && !action.specifier.startsWith(`${FLOW_PACKAGE_NAME}@`) || action.specifier.includes("/") || action.specifier.includes("\\") || typeof action.resolvedVersion !== "string" || !isExactFlowVersion(action.resolvedVersion) || action.path !== join(paths.packageCacheRoot, action.specifier)) {
+    throw new Error(`${action.path}: cache recovery metadata is incomplete`);
+  }
+  const expectedStagingPath = join(paths.cacheRecoveryRoot, journal.runId, sha256(action.path).slice(0, 12), basename(action.path));
+  if (action.stagingPath !== expectedStagingPath) {
+    throw new Error(`${action.path}: cache staging path does not match journal`);
+  }
+  return {
+    path: action.path,
+    specifier: action.specifier,
+    resolvedVersion: action.resolvedVersion,
+    status: "inactive"
+  };
+}
+async function rollbackInterruptedConfigAction(options) {
+  const { action, journal, journalPath, paths } = options;
+  const descriptor = journalConfigDescriptor(paths, action);
+  await assertSafeMutationPath(descriptor.safetyRoot, action.path);
+  const currentMetadata = await optionalLstat(action.path);
+  if (currentMetadata?.isSymbolicLink() || currentMetadata && !currentMetadata.isFile()) {
+    throw new Error(`${action.path}: interrupted config is not a regular file`);
+  }
+  const current = currentMetadata ? await readRegularFileWithoutFollowing(action.path) : null;
+  if (action.originalAbsent === true) {
+    const expectedRecoveryPath = join(dirname(action.path), ".flow-activation-recovery", journal.runId, `${basename(action.path)}-${sha256(action.path).slice(0, 12)}`);
+    if (action.recoveryPath !== expectedRecoveryPath) {
+      throw new Error(`${action.path}: created-config recovery path is invalid`);
+    }
+    if (current === null)
+      return;
+    if (!action.appliedDigest || sha256(current) !== action.appliedDigest) {
+      throw new Error(`${action.path}: interrupted created config changed; automatic recovery refused`);
+    }
+    await assertSafeMutationPath(descriptor.safetyRoot, action.recoveryPath);
+    if (await optionalLstat(action.recoveryPath)) {
+      throw new Error(`${action.path}: created-config recovery path is occupied`);
+    }
+    await mkdir(dirname(action.recoveryPath), {
+      recursive: true,
+      mode: 448
+    });
+    await rename(action.path, action.recoveryPath);
+    return;
+  }
+  const expectedBackupPath = join(dirname(journalPath), "configs", `${descriptor.source}-${sha256(action.path).slice(0, 12)}.backup`);
+  if (action.backupPath !== expectedBackupPath) {
+    throw new Error(`${action.path}: config backup path is invalid`);
+  }
+  const backup = await readRegularFileWithoutFollowing(action.backupPath, MAX_LOCAL_PLUGIN_BYTES);
+  if (current === null) {
+    throw new Error(`${action.path}: interrupted config is missing`);
+  }
+  if (sha256(current) === sha256(backup))
+    return;
+  if (!action.appliedDigest || sha256(current) !== action.appliedDigest) {
+    throw new Error(`${action.path}: interrupted config changed; automatic recovery refused`);
+  }
+  await replaceKnownConfigContent({
+    descriptor,
+    expectedDigest: action.appliedDigest,
+    content: backup,
+    mode: action.originalMode ?? 384,
+    runId: journal.runId
+  });
+}
+async function rollbackInterruptedRemovalAction(options) {
+  const { action, journal, paths } = options;
+  let safetyRoot;
+  let verifyStaged;
+  if (action.action === "remove-wrapper") {
+    const { wrapper, safetyRoot: wrapperSafetyRoot } = journalOwnedWrapper(paths, journal, action);
+    safetyRoot = wrapperSafetyRoot;
+    verifyStaged = () => verifyOwnedWrapper({ ...wrapper, path: action.stagingPath });
+  } else {
+    const artifact = journalCacheArtifact(paths, journal, action);
+    safetyRoot = dirname(paths.cacheRoot);
+    verifyStaged = () => verifyCacheArtifact({ ...artifact, path: action.stagingPath }, journal.target);
+  }
+  await assertSafeMutationPath(safetyRoot, action.path);
+  await assertSafeMutationPath(safetyRoot, action.stagingPath);
+  const original = await optionalLstat(action.path);
+  const staged = await optionalLstat(action.stagingPath);
+  if (original && staged) {
+    throw new Error(`${action.path}: both original and staged artifacts exist`);
+  }
+  if (original) {
+    if (original.isSymbolicLink()) {
+      throw new Error(`${action.path}: restored artifact is symbolic`);
+    }
+    return;
+  }
+  if (!staged || staged.isSymbolicLink()) {
+    throw new Error(`${action.path}: interrupted staged artifact is missing`);
+  }
+  await verifyStaged();
+  await mkdir(dirname(action.path), { recursive: true });
+  await rename(action.stagingPath, action.path);
+}
+async function rollbackInterruptedJournal(journal, journalPath, paths) {
+  for (const action of journal.actions.toReversed()) {
+    if (action.state === "rolled-back")
+      continue;
+    if (action.action === "rewrite-config") {
+      await rollbackInterruptedConfigAction({
+        journal,
+        journalPath,
+        action,
+        paths
+      });
+    } else {
+      await rollbackInterruptedRemovalAction({ journal, action, paths });
+    }
+    action.state = "rolled-back";
+    delete action.error;
+    await writeJournal(journalPath, journal);
+  }
+  journal.state = "rolled-back";
+  delete journal.ownerPid;
+  delete journal.error;
+  await writeJournal(journalPath, journal);
+}
+async function finishCommittedJournalCleanup(journal, journalPath, paths) {
+  const removalActions = journal.actions.filter((action) => action.action === "remove-wrapper" || action.action === "remove-cache");
+  for (const action of removalActions) {
+    let safetyRoot;
+    let verifyStaged;
+    if (action.action === "remove-wrapper") {
+      const { wrapper, safetyRoot: wrapperSafetyRoot } = journalOwnedWrapper(paths, journal, action);
+      safetyRoot = wrapperSafetyRoot;
+      verifyStaged = () => verifyOwnedWrapper({ ...wrapper, path: action.stagingPath });
+    } else {
+      const artifact = journalCacheArtifact(paths, journal, action);
+      safetyRoot = dirname(paths.cacheRoot);
+      verifyStaged = () => verifyCacheArtifact({ ...artifact, path: action.stagingPath }, journal.target);
+    }
+    await assertSafeMutationPath(safetyRoot, action.path);
+    await assertSafeMutationPath(safetyRoot, action.stagingPath);
+    if (await optionalLstat(action.path)) {
+      throw new Error(`${action.path}: obsolete original path reappeared after activation commit`);
+    }
+    if (await optionalLstat(action.stagingPath)) {
+      await verifyStaged();
+      await rm(action.stagingPath, {
+        recursive: action.action === "remove-cache"
+      });
+    }
+    if (await optionalLstat(action.stagingPath)) {
+      throw new Error(`${action.path}: obsolete staged artifact still exists`);
+    }
+    action.deleted = true;
+    await removeEmptyDirectory(dirname(action.stagingPath));
+    await writeJournal(journalPath, journal);
+  }
+  for (const runDirectory of new Set(removalActions.map((action) => dirname(dirname(action.stagingPath))))) {
+    await removeEmptyDirectory(runDirectory);
+  }
+  await removeEmptyDirectory(paths.cacheRecoveryRoot);
+  journal.state = "complete";
+  delete journal.ownerPid;
+  delete journal.error;
+  await writeJournal(journalPath, journal);
+}
+async function reconcileIncompleteActivationJournals(paths, pathOptions) {
+  const failures = [];
+  for (const entry of await readActivationJournalEntries(paths)) {
+    if (entry.error) {
+      failures.push(`recovery journal could not be inspected safely at ${entry.journalPath}: ${entry.error}`);
+      continue;
+    }
+    const journal = entry.journal;
+    if (TERMINAL_JOURNAL_STATES.has(journal.state))
+      continue;
+    if (journal.format === "flow-activation-journal-v1") {
+      failures.push(`${entry.journalPath}: legacy activation recovery is incomplete in state ${journal.state}; follow its manual recovery guidance before retrying`);
+      continue;
+    }
+    if (journal.ownerPid !== undefined && processIsAlive(journal.ownerPid)) {
+      failures.push(`${entry.journalPath}: activation is still owned by running process ${journal.ownerPid}`);
+      continue;
+    }
+    if (journal.state === "rollback-failed") {
+      failures.push(`${entry.journalPath}: previous rollback failed; follow its manual recovery guidance before retrying`);
+      continue;
+    }
+    const journalPaths = resolveActivationPaths(journal.project, pathOptions);
+    if (journalPaths.journalRoot !== paths.journalRoot) {
+      failures.push(`${entry.journalPath}: journal resolves to a different recovery root`);
+      continue;
+    }
+    try {
+      if (journal.state === "committed" || journal.state === "cleanup-failed") {
+        await finishCommittedJournalCleanup(journal, entry.journalPath, journalPaths);
+      } else {
+        await rollbackInterruptedJournal(journal, entry.journalPath, journalPaths);
+      }
+    } catch (error) {
+      journal.state = journal.state === "committed" || journal.state === "cleanup-failed" ? "cleanup-failed" : "rollback-failed";
+      journal.error = error instanceof Error ? error.message : String(error);
+      delete journal.ownerPid;
+      try {
+        await writeJournal(entry.journalPath, journal);
+      } catch {}
+      failures.push(`${entry.journalPath}: ${journal.error}`);
+    }
+  }
+  return failures;
+}
 async function applyFlowActivation(options) {
   const target = resolveActivationTarget(options.target);
+  const paths = resolveActivationPaths(options.project, options.paths);
+  const recoveryRefusals = options.apply === true ? await reconcileIncompleteActivationJournals(paths, options.paths) : [];
   const before = await checkFlowActivation({
     project: options.project,
     target,
     ...options.paths ? { paths: options.paths } : {}
   });
-  const refusals = activationRefusals(before);
+  const refusals = [
+    ...recoveryRefusals,
+    ...activationRefusals(before),
+    ...downgradeRefusals(before)
+  ];
   const snapshots = [];
   for (const descriptor of configDescriptors(before.paths)) {
     try {
@@ -1375,7 +1921,7 @@ async function applyFlowActivation(options) {
       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`);
+        throw new Error(`${wrapper.path}: removable wrapper or staging parent is not writable; remove it manually and rerun activation-apply`);
       }
       wrappers.push(wrapper);
     } catch (error) {
@@ -1444,17 +1990,17 @@ async function applyFlowActivation(options) {
   const canonicalSnapshot = snapshots.find((snapshot) => snapshot.descriptor.path === canonicalPath);
   for (const wrapper of wrappers) {
     plan.push({
-      action: "quarantine-wrapper",
+      action: "remove-wrapper",
       scope: wrapper.scope,
       path: wrapper.path,
-      detail: "move marker-proven wrapper outside OpenCode plugin discovery"
+      detail: "permanently remove the proven Flow wrapper after reversible staging and activation verification"
     });
   }
   for (const artifact of inactiveCache) {
     plan.push({
-      action: "quarantine-cache",
+      action: "remove-cache",
       path: artifact.path,
-      detail: `move proven inactive Flow ${artifact.resolvedVersion} cache artifact; never clear the cache root`
+      detail: `permanently remove proven inactive Flow ${artifact.resolvedVersion} after reversible staging; preserve the cache root and unrelated packages`
     });
   }
   const base = {
@@ -1480,6 +2026,8 @@ async function applyFlowActivation(options) {
     const action = {
       action: "rewrite-config",
       path: snapshot.descriptor.path,
+      source: snapshot.descriptor.source,
+      scope: snapshot.descriptor.scope,
       originalAbsent: !snapshot.exists,
       originalMode: snapshot.mode,
       state: "pending"
@@ -1493,24 +2041,31 @@ async function applyFlowActivation(options) {
   }
   for (const wrapper of wrappers) {
     actions.push({
-      action: "quarantine-wrapper",
+      action: "remove-wrapper",
       path: wrapper.path,
-      recoveryPath: join(wrapperRecoveryRoot(before.paths, wrapper), runId, `${basename(wrapper.path)}-${sha256(wrapper.path).slice(0, 12)}`),
+      source: wrapper.source,
+      scope: wrapper.scope,
+      resolvedVersion: wrapper.version,
+      ownership: wrapper.ownership,
+      stagingPath: join(wrapperRecoveryRoot(before.paths, wrapper), runId, sha256(wrapper.path).slice(0, 12), basename(wrapper.path)),
       state: "pending"
     });
   }
   for (const artifact of inactiveCache) {
     actions.push({
-      action: "quarantine-cache",
+      action: "remove-cache",
       path: artifact.path,
-      recoveryPath: join(before.paths.cacheRecoveryRoot, runId, `${basename(artifact.path)}-${sha256(artifact.path).slice(0, 12)}`),
+      ...artifact.resolvedVersion ? { resolvedVersion: artifact.resolvedVersion } : {},
+      specifier: artifact.specifier,
+      stagingPath: join(before.paths.cacheRecoveryRoot, runId, sha256(artifact.path).slice(0, 12), basename(artifact.path)),
       state: "pending"
     });
   }
   const journal = {
-    format: "flow-activation-journal-v1",
+    format: "flow-activation-journal-v2",
     runId,
     createdAt: new Date().toISOString(),
+    ownerPid: process.pid,
     project: before.project,
     target,
     scope: options.scope,
@@ -1529,6 +2084,8 @@ async function applyFlowActivation(options) {
       refusals: [...new Set([...base.refusals, message])]
     };
   }
+  let removalCommitStarted = false;
+  let committedAfter;
   try {
     for (const snapshot of changedSnapshots) {
       await assertUnchangedConfig(snapshot);
@@ -1560,68 +2117,116 @@ async function applyFlowActivation(options) {
     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 atomicWriteConfig(snapshot, content, runId);
+      if (action)
+        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`);
+      const action = actions.find((candidate) => candidate.action === "remove-wrapper" && candidate.path === wrapper.path);
+      if (!action?.stagingPath) {
+        throw new Error(`${wrapper.path}: missing wrapper staging path`);
       }
       await verifyOwnedWrapper(wrapper);
       await assertSafeMutationPath(wrapperMutationSafetyRoot(before.paths, wrapper), wrapper.path);
-      await mkdir(dirname(action.recoveryPath), {
+      await assertSafeMutationPath(wrapperMutationSafetyRoot(before.paths, wrapper), action.stagingPath);
+      await mkdir(dirname(action.stagingPath), {
         recursive: true,
         mode: 448
       });
-      await rename(wrapper.path, action.recoveryPath);
+      await rename(wrapper.path, action.stagingPath);
       action.state = "complete";
       await writeJournal(journalPath, journal);
-      await options.afterMutation?.(plan.find((operation) => operation.action === "quarantine-wrapper" && operation.path === wrapper.path));
+      await options.afterMutation?.(plan.find((operation) => operation.action === "remove-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`);
+      const action = actions.find((candidate) => candidate.action === "remove-cache" && candidate.path === artifact.path);
+      if (!action?.stagingPath) {
+        throw new Error(`${artifact.path}: missing cache staging path`);
       }
       await verifyCacheArtifact(artifact, target);
       await assertSafeMutationPath(dirname(before.paths.cacheRoot), artifact.path);
-      await mkdir(dirname(action.recoveryPath), {
+      await assertSafeMutationPath(dirname(before.paths.cacheRoot), action.stagingPath);
+      await mkdir(dirname(action.stagingPath), {
         recursive: true,
         mode: 448
       });
-      await rename(artifact.path, action.recoveryPath);
+      await rename(artifact.path, action.stagingPath);
       action.state = "complete";
       await writeJournal(journalPath, journal);
-      await options.afterMutation?.(plan.find((operation) => operation.action === "quarantine-cache" && operation.path === artifact.path));
+      await options.afterMutation?.(plan.find((operation) => operation.action === "remove-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 atomicWriteConfig(targetConfig, targetContent, runId);
+      if (targetAction)
+        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,
+      ignoreRecoveryRunId: runId,
       ...options.paths ? { paths: options.paths } : {}
     });
     if (!after.singleVersionSatisfied) {
       throw new Error(`post-apply inventory did not prove a single version: ${after.reasons.join("; ")}`);
     }
+    committedAfter = after;
+    for (const wrapper of wrappers) {
+      const action = actions.find((candidate) => candidate.action === "remove-wrapper" && candidate.path === wrapper.path);
+      if (!action?.stagingPath) {
+        throw new Error(`${wrapper.path}: missing staged wrapper at commit`);
+      }
+      await verifyOwnedWrapper({ ...wrapper, path: action.stagingPath });
+    }
+    for (const artifact of inactiveCache) {
+      const action = actions.find((candidate) => candidate.action === "remove-cache" && candidate.path === artifact.path);
+      if (!action?.stagingPath) {
+        throw new Error(`${artifact.path}: missing staged cache at commit`);
+      }
+      await verifyCacheArtifact({ ...artifact, path: action.stagingPath }, target);
+    }
+    const removalActions = actions.filter((candidate) => candidate.action === "remove-wrapper" || candidate.action === "remove-cache");
+    if (removalActions.length > 0) {
+      journal.state = "committed";
+      await writeJournal(journalPath, journal);
+      removalCommitStarted = true;
+      await options.afterRemovalCommit?.();
+    }
+    for (const action of removalActions) {
+      if (!action.stagingPath) {
+        throw new Error(`${action.path}: missing staging path at deletion`);
+      }
+      await rm(action.stagingPath, {
+        recursive: action.action === "remove-cache"
+      });
+      if (await optionalLstat(action.stagingPath)) {
+        throw new Error(`${action.path}: staged obsolete artifact still exists`);
+      }
+      action.deleted = true;
+      await removeEmptyDirectory(dirname(action.stagingPath));
+      await writeJournal(journalPath, journal);
+    }
+    for (const runDirectory of new Set(removalActions.flatMap((action) => action.stagingPath ? [dirname(dirname(action.stagingPath))] : []))) {
+      await removeEmptyDirectory(runDirectory);
+    }
+    await removeEmptyDirectory(before.paths.cacheRecoveryRoot);
     journal.state = "complete";
+    delete journal.ownerPid;
     await writeJournal(journalPath, journal);
     return {
       ...base,
@@ -1631,6 +2236,29 @@ async function applyFlowActivation(options) {
       refusals: []
     };
   } catch (error) {
+    if (removalCommitStarted) {
+      journal.state = "cleanup-failed";
+      delete journal.ownerPid;
+      journal.error = error instanceof Error ? error.message : String(error);
+      try {
+        await writeJournal(journalPath, journal);
+      } catch {}
+      return {
+        ...base,
+        status: "refused",
+        recovery: { runId, journalPath },
+        ...committedAfter ? { after: committedAfter } : {},
+        failure: {
+          message: journal.error,
+          recoveryState: "cleanup-failed",
+          guidance: [
+            "The newest Flow activation is committed and remains authoritative; do not restore an older config or plugin source.",
+            `Inspect ${journalPath} and permanently delete each remaining remove-wrapper or remove-cache stagingPath after verifying it still contains only the recorded obsolete Flow version.`
+          ]
+        },
+        refusals: [journal.error]
+      };
+    }
     journal.state = "failed";
     journal.error = error instanceof Error ? error.message : String(error);
     try {
@@ -1646,6 +2274,7 @@ async function applyFlowActivation(options) {
     });
     const recoveryState = rollbackFailures.length === 0 ? "rolled-back" : "rollback-failed";
     journal.state = recoveryState;
+    delete journal.ownerPid;
     if (rollbackFailures.length > 0) {
       journal.error = `${journal.error ?? "apply failed"}; rollback: ${rollbackFailures.join("; ")}`;
     }
@@ -1653,11 +2282,11 @@ async function applyFlowActivation(options) {
       await writeJournal(journalPath, journal);
     } catch {}
     const guidance = recoveryState === "rolled-back" ? [
-      "All completed mutations were restored from exact backups or quarantine renames.",
+      "All completed mutations were restored from exact backups or reversible staging moves.",
       `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.`,
+      `Inspect ${journalPath}; for rollback-failed actions, restore backupPath to path or rename stagingPath back to path only after verifying the destination is absent or unchanged.`,
       "Do not delete the recovery directory until activation-check succeeds."
     ];
     return {
@@ -1706,7 +2335,7 @@ 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-]+)*)?$/;
+var SEMVER_PATTERN2 = /^(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 configuredHome2() {
   return process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || homedir2();
 }
@@ -1799,7 +2428,7 @@ function parseMarker(content) {
   return { version, files };
 }
 function assertSupportedLegacyVersion(version) {
-  const match = SEMVER_PATTERN.exec(version);
+  const match = SEMVER_PATTERN2.exec(version);
   if (!match) {
     throw new Error(`marker version '${version}' is not a valid semantic version`);
   }
@@ -1983,17 +2612,19 @@ async function cleanupLegacySkills(options) {
 function usage() {
   return [
     "usage:",
+    "  opencode-plugin-flow install --project <absolute-path> --scope <global|project> [--json]",
     "  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",
+    "  install             Converge immediately to this package's exact version and remove proven older copies",
+    "  activation-check    Inventory global sources, one selected project, 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",
     "",
     "activation options:",
-    "  --project <path>    Absolute project/worktree path whose sources are inventoried",
+    "  --project <path>    Absolute project/worktree path; other project trees are not scanned",
     "  --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",
@@ -2045,6 +2676,8 @@ function writeActivationCheck(report, json) {
   process.stdout.write(`Flow activation check: ${report.singleVersionSatisfied ? "satisfied" : "not satisfied"}
 `);
   process.stdout.write(`- project: ${report.project}
+`);
+  process.stdout.write(`- coverage: global sources plus the selected project; other project trees are not scanned
 `);
   process.stdout.write(`- target: opencode-plugin-flow@${report.target}
 `);
@@ -2085,18 +2718,25 @@ function writeActivationApply(report, json) {
   process.stdout.write(`Flow activation ${report.mode}: ${report.status}
 `);
   process.stdout.write(`- project: ${report.project}
+`);
+  process.stdout.write(`- coverage: global sources plus the selected project; other project trees are not scanned
 `);
   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.status === "refused" && report.plan.length > 0) {
+    process.stdout.write(`- blocked plan (not executed):
+`);
+  }
+  for (const operation of report.plan) {
+    const action = report.status === "refused" ? `would-${operation.action}` : operation.action;
+    process.stdout.write(`- ${action}: ${operation.path}
+  ${operation.detail}
 `);
   }
   if (report.recovery) {
@@ -2204,6 +2844,29 @@ async function runActivationApply(flags) {
   if (report.status === "refused")
     process.exitCode = 1;
 }
+async function runInstall(flags) {
+  const parsed = parseActivationFlags(flags);
+  const scope = activationScope(parsed?.scope);
+  if (!parsed || parsed.apply || parsed.target || !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: true
+  });
+  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));
@@ -2237,6 +2900,10 @@ async function main(argv) {
     await runActivationCheck(flags);
     return;
   }
+  if (command === "install") {
+    await runInstall(flags);
+    return;
+  }
   if (command === "activation-apply") {
     await runActivationApply(flags);
     return;
@@ -2255,4 +2922,4 @@ main(process.argv).catch((error) => {
   process.exitCode = 1;
 });
 
-//# debugId=963853A3888CECEA64756E2164756E21
+//# debugId=C55B4CE51FD9A58B64756E2164756E21