@brainervirus/workit-core 2.0.2 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/core/detect-hosts.ts

@@ -1,20 +1,24 @@
-// Host presence detection for the CLI setup wizard: which tools are installed
-// (CLI on PATH or home config marker — never a subprocess probe) and which of
-// the wizard-managed hosts already carry a workit registration. The configured
-// signal reuses planUninstall's installed bit so detection and uninstall can
-// never disagree; codex/pi are presence-only (their setup runs via cutover).
-import { existsSync, readdirSync } from "node:fs";
+// Host presence detection uses actual CLI executables or supported desktop app
+// locations; configuration directories alone never count as installation.
+// Existing registrations reuse uninstall planning so the two paths agree.
+import { readdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { commandOnPath } from "./doctor";
 import { planUninstall, type UninstallPaths } from "./uninstall";
-
-export type HostId = "opencode" | "cursor" | "codex" | "pi";
+import {
+  findHostExecutable,
+  installedHostApp,
+  isCodexWorkitInstalled,
+  isPiWorkitInstalled,
+  type HostId,
+} from "./host-install";
+export type { HostId } from "./host-install";
 
 export type HostDetection = {
-  /** CLI on PATH or a home config marker exists. */
+  /** Host executable or supported desktop application is present. */
   detected: boolean;
-  /** A workit registration is present (opencode/cursor only; always false). */
+  /** A Workit registration is present for this host. */
   configured: boolean;
 };
 
@@ -22,15 +26,8 @@ export type DetectHostsOptions = UninstallPaths;
 
 const HOSTS: HostId[] = ["opencode", "cursor", "codex", "pi"];
 
-const HOME_MARKERS: Record<HostId, string[]> = {
-  opencode: [path.join(".config", "opencode")],
-  cursor: [".cursor"],
-  codex: [".codex"],
-  pi: [".pi"],
-};
-
-/** Hosts the wizard Apply path registers (codex/pi set up via cutover). */
-export const WIZARD_HOSTS: HostId[] = ["opencode", "cursor"];
+/** Hosts the setup wizard configures through their native install paths. */
+export const WIZARD_HOSTS: HostId[] = [...HOSTS];
 
 /** Detected hosts the wizard can preselect (presence ∩ wizard-managed). */
 export function preselectedPlatforms(detection: Record<HostId, HostDetection>): string[] {
@@ -51,15 +48,20 @@ export function detectHosts(options: DetectHostsOptions = {}): Record<HostId, Ho
   // Same chain as uninstall path resolution: explicit home > env.HOME > homedir.
   const home = options.home ?? env.HOME ?? os.homedir();
   // Pure reader: classifies the installed state, never writes.
-  const plan = planUninstall(options);
+  const plan = planUninstall({ ...options, home, env });
   const configuredByHost = new Map(plan.hosts.map((h) => [h.host, h.installed]));
   const found = emptyDetection();
   for (const host of HOSTS) {
     const detected =
-      cliFound(host, env, home) || HOME_MARKERS[host].some((m) => existsSync(path.join(home, m)));
+      findHostExecutable(host, { home, env }) !== null || installedHostApp(host, home, env);
     found[host] = {
       detected,
-      configured: WIZARD_HOSTS.includes(host) && (configuredByHost.get(host) ?? false),
+      configured:
+        host === "codex"
+          ? isCodexWorkitInstalled(home, env) || (configuredByHost.get(host) ?? false)
+          : host === "pi"
+            ? isPiWorkitInstalled(home, env) || (configuredByHost.get(host) ?? false)
+            : (configuredByHost.get(host) ?? false),
     };
   }
   return found;

package/src/core/doctor.ts

@@ -217,11 +217,18 @@ const parsesAsConfigObject = (p: string): boolean => {
   }
 };
 
-// OpenCode accepts `plugin` as a string or an array; normalize before reading.
+// V2 uses plugins; V1 accepts plugin as a string or array. Inspect both.
 const pluginEntries = (cfg: Record<string, any> | null): string[] => {
-  const plugin = cfg?.plugin;
-  const list = Array.isArray(plugin) ? plugin : typeof plugin === "string" ? [plugin] : [];
-  return list.map(String).filter(isWorkitPlugin);
+  const entries = [cfg?.plugins, cfg?.plugin].flatMap((value) =>
+    Array.isArray(value) ? value : typeof value === "string" ? [value] : [],
+  );
+  return [
+    ...new Set(
+      entries.filter(
+        (entry): entry is string => typeof entry === "string" && isWorkitPlugin(entry),
+      ),
+    ),
+  ];
 };
 
 export const commandOnPath = (name: string, env: NodeJS.ProcessEnv): boolean => {

package/src/core/host-install.ts

@@ -0,0 +1,458 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type HostId = "opencode" | "cursor" | "codex" | "pi";
+
+/** A reviewed argv vector. Arguments are never composed into a shell string. */
+export type HostInstallCommand = {
+  command: string;
+  args: string[];
+  cwd?: string;
+  purpose: string;
+  /** Optional managed package tree to stage, for Cursor's local plugin copy. */
+  packageRoot?: string;
+  packageTarget?: string;
+  skipWhenOutputIncludes?: string;
+};
+
+export type HostCommandResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+export type HostCommandRunner = (step: HostInstallCommand) => HostCommandResult;
+export type HostCommandContext = { home?: string; env?: NodeJS.ProcessEnv };
+
+export function hostCommand(
+  name: string,
+  args: string[],
+  options: HostInstallOptions = {},
+): HostInstallCommand {
+  const executable = findHostExecutable(name, options);
+  if (!executable)
+    throw new Error(`${name} executable was not found on PATH or supported user bin directories`);
+  if (process.platform === "win32" && /\.(?:cmd|bat)$/i.test(executable)) {
+    const node = findHostExecutable("node", options);
+    if (!node) throw new Error(`Node.js is required to run the ${name} Windows shim`);
+    const script = resolveWindowsShimScript(executable);
+    if (!script)
+      throw new Error(`could not resolve the ${name} Windows shim to a JavaScript entrypoint`);
+    return { command: node, args: [script, ...args], cwd: options.cwd, purpose: `${name} CLI` };
+  }
+  return { command: executable, args, cwd: options.cwd, purpose: `${name} CLI` };
+}
+
+export function resolveWindowsShimEntry(
+  contents: string,
+  shim: string,
+  exists: (candidate: string) => boolean = existsSync,
+): string | null {
+  const root = path.win32.dirname(shim);
+  const matches = contents.matchAll(/(["']?)([^\r\n"']*node_modules[\\/][^\r\n"']+?\.js)\1/gi);
+  for (const match of matches) {
+    const raw = match[2].replace(/%~?dp0%?/gi, root);
+    const candidate = path.win32.isAbsolute(raw) ? raw : path.win32.resolve(root, raw);
+    if (exists(candidate)) return candidate;
+  }
+  return null;
+}
+
+const resolveWindowsShimScript = (shim: string): string | null => {
+  try {
+    const contents = readFileSync(shim, "utf8");
+    return resolveWindowsShimEntry(contents, shim);
+  } catch {
+    return null;
+  }
+};
+
+export type HostInstallOptions = {
+  home?: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  packageVersion?: string;
+  alreadyInstalled?: boolean;
+  targetDir?: string;
+  mode?: "install" | "upgrade";
+};
+
+const MARKETPLACE = "https://github.com/BrainerVirus/workit.git";
+const CODEX_MARKETPLACE_NAME = "workflow-toolkit";
+const validPackageVersion = (value: string): boolean =>
+  value === "latest" || /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
+
+const nodePrerequisite = (options: HostInstallOptions): HostInstallCommand => {
+  const node = findHostExecutable("node", options);
+  if (!node) throw new Error("Workit host packages require Node.js 24+; install Node.js and retry");
+  return {
+    command: node,
+    args: [
+      "-e",
+      'const v=Number(process.versions.node.split(".")[0]);if(v<24){console.error(`Workit host packages require Node.js 24+ (found ${process.versions.node})`);process.exit(1)}',
+    ],
+    cwd: options.cwd,
+    purpose: "Check the Node.js 24+ package runtime requirement",
+  };
+};
+
+/** Resolve host executables through PATH plus common user-level Node managers. */
+export function findHostExecutable(
+  name: string,
+  options: { home?: string; env?: NodeJS.ProcessEnv } = {},
+): string | null {
+  const env = options.env ?? process.env;
+  const home = options.home ?? env.HOME ?? os.homedir();
+  const suffixes = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
+  const dirs = (env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  dirs.push(path.join(home, ".local", "bin"), path.join(home, ".asdf", "shims"));
+  for (const [base, tail] of [
+    [path.join(home, ".local", "share", "fnm", "node-versions"), path.join("installation", "bin")],
+    [path.join(home, ".nvm", "versions", "node"), "bin"],
+  ] as const) {
+    try {
+      for (const entry of readdirSync(base, { withFileTypes: true })) {
+        if (entry.isDirectory()) dirs.push(path.join(base, entry.name, tail));
+      }
+    } catch {
+      // A missing version-manager directory is normal.
+    }
+  }
+  for (const dir of dirs) {
+    for (const suffix of suffixes) {
+      const candidate = path.join(dir, `${name}${suffix}`);
+      try {
+        if (statSync(candidate).isFile()) {
+          if (process.platform === "win32") return candidate;
+          accessSync(candidate, constants.X_OK);
+          return candidate;
+        }
+      } catch {
+        // Continue through PATH entries and platform shims.
+      }
+    }
+  }
+  return null;
+}
+
+export const isPiWorkitInstalled = (
+  home: string,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean => {
+  const settings = path.join(
+    env.PI_CODING_AGENT_DIR ?? path.join(home, ".pi", "agent"),
+    "settings.json",
+  );
+  try {
+    const document = JSON.parse(readFileSync(settings, "utf8")) as { packages?: unknown[] };
+    return (document.packages ?? []).some((entry) => {
+      const source =
+        entry && typeof entry === "object" && !Array.isArray(entry)
+          ? (entry as { source?: unknown }).source
+          : entry;
+      const value = String(source).replaceAll("\\", "/").replace(/\/+$/, "");
+      return (
+        /^npm:@brainervirus\/workit-pi(?:@[^/]+)?$/.test(value) ||
+        value === "@brainervirus/workit-pi" ||
+        /(?:^|\/)packages\/workit-pi$/.test(value)
+      );
+    });
+  } catch {
+    return false;
+  }
+};
+
+const isCanonicalCodexPackage = (root: string): boolean => {
+  for (const file of [
+    path.join(root, ".codex-plugin", "plugin.json"),
+    path.join(root, "package.json"),
+  ]) {
+    try {
+      const manifest = JSON.parse(readFileSync(file, "utf8")) as {
+        name?: string;
+        repository?: string | { url?: string };
+      };
+      const repository =
+        typeof manifest.repository === "string" ? manifest.repository : manifest.repository?.url;
+      if (
+        (manifest.name === "workit" || manifest.name === "@brainervirus/workit-codex") &&
+        repository?.replace(/\.git$/, "").toLowerCase() === "https://github.com/brainervirus/workit"
+      )
+        return true;
+    } catch {
+      // Try the other manifest path.
+    }
+  }
+  return false;
+};
+
+export const isCodexWorkitInstalled = (
+  home: string,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean => {
+  const codexHome = env.CODEX_HOME ?? path.join(home, ".codex");
+  const isPackageOrVersionDirectory = (root: string): boolean => {
+    if (isCanonicalCodexPackage(root)) return true;
+    try {
+      return readdirSync(root, { withFileTypes: true }).some(
+        (entry) => entry.isDirectory() && isCanonicalCodexPackage(path.join(root, entry.name)),
+      );
+    } catch {
+      return false;
+    }
+  };
+  if (isPackageOrVersionDirectory(path.join(codexHome, "plugins", "workit"))) return true;
+  const root = path.join(codexHome, "plugins", "cache");
+  try {
+    for (const marketplace of readdirSync(root, { withFileTypes: true })) {
+      if (!marketplace.isDirectory()) continue;
+      if (isPackageOrVersionDirectory(path.join(root, marketplace.name, "workit"))) return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+};
+
+export function installedHostApp(
+  host: HostId,
+  home: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+  exists: (candidate: string) => boolean = existsSync,
+): boolean {
+  const candidates: string[] = [];
+  const pathApi = platform === "win32" ? path.win32 : path;
+  if (platform === "darwin") {
+    const app =
+      host === "cursor"
+        ? "Cursor.app"
+        : host === "codex"
+          ? "Codex.app"
+          : host === "opencode"
+            ? "OpenCode.app"
+            : "";
+    if (app) candidates.push(`/Applications/${app}`, pathApi.join(home, "Applications", app));
+  } else if (platform === "win32") {
+    const local = env.LOCALAPPDATA ?? pathApi.join(home, "AppData", "Local");
+    if (host === "cursor") candidates.push(pathApi.join(local, "Programs", "Cursor", "Cursor.exe"));
+    if (host === "codex") candidates.push(pathApi.join(local, "Programs", "Codex", "Codex.exe"));
+    if (host === "opencode")
+      candidates.push(pathApi.join(local, "Programs", "OpenCode", "OpenCode.exe"));
+  }
+  return candidates.some(exists);
+}
+
+/** Plan the host-native registration commands used by setup and upgrade. */
+export function planHostInstall(
+  host: HostId,
+  options: HostInstallOptions = {},
+): HostInstallCommand[] {
+  const env = options.env ?? process.env;
+  const home = options.home ?? env.HOME ?? os.homedir();
+  const cwd = options.cwd ?? process.cwd();
+  const version = options.packageVersion ?? "latest";
+  if (!validPackageVersion(version))
+    throw new Error(`unsupported package version selector: ${version}`);
+  if (options.alreadyInstalled && options.mode !== "upgrade") return [];
+  const upgrading = options.mode === "upgrade";
+  if (host === "codex") {
+    if (!upgrading && isCodexWorkitInstalled(home, env)) return [];
+    const base = hostCommand("codex", [], { home, cwd, env });
+    return [
+      nodePrerequisite({ home, cwd, env }),
+      {
+        ...base,
+        args: [...base.args, "plugin", "marketplace", "list"],
+        purpose: "Check whether the Workit marketplace is already registered",
+      },
+      {
+        ...base,
+        args: [
+          ...base.args,
+          "plugin",
+          "marketplace",
+          upgrading ? "upgrade" : "add",
+          ...(upgrading ? [CODEX_MARKETPLACE_NAME] : [MARKETPLACE]),
+        ],
+        purpose: upgrading
+          ? "Refresh the Workit Codex marketplace"
+          : "Register the Workit Codex marketplace",
+        ...(upgrading ? {} : { skipWhenOutputIncludes: CODEX_MARKETPLACE_NAME }),
+      },
+      {
+        ...base,
+        args: [...base.args, "plugin", "add", `workit@${CODEX_MARKETPLACE_NAME}`],
+        purpose: upgrading ? "Refresh the Workit Codex plugin" : "Install the Workit Codex plugin",
+      },
+    ];
+  }
+  if (host === "pi") {
+    if (!upgrading && isPiWorkitInstalled(home, env)) return [];
+    const base = hostCommand("pi", [], { home, cwd, env });
+    return [
+      nodePrerequisite({ home, cwd, env }),
+      {
+        ...base,
+        args: upgrading
+          ? [...base.args, "update", "--extension", "npm:@brainervirus/workit-pi"]
+          : [...base.args, "install", `npm:@brainervirus/workit-pi@${version}`],
+        purpose: upgrading
+          ? "Update the Workit Pi package"
+          : "Install the Workit Pi package in personal Pi settings",
+      },
+    ];
+  }
+  if (host === "cursor") {
+    const node = findHostExecutable("node", { home, env });
+    if (!node)
+      throw new Error("Workit host packages require Node.js 24+; install Node.js and retry");
+    const npm = findHostExecutable("npm", { home, env });
+    const npmCli = npm ? findNpmCli(npm) : null;
+    if (!npmCli)
+      throw new Error("npm CLI could not be resolved; install Node.js 24+ and npm, then retry");
+    const stage = path.join(home, ".cursor", "plugins", "local", ".workit-package-bootstrap");
+    const target = options.targetDir ?? path.join(home, ".cursor", "plugins", "local", "workit");
+    return [
+      nodePrerequisite({ home, cwd, env }),
+      {
+        command: node,
+        args: [
+          npmCli,
+          "install",
+          "--prefix",
+          stage,
+          "--no-save",
+          "--package-lock=false",
+          `@brainervirus/workit-cursor@${version}`,
+        ],
+        cwd,
+        purpose: upgrading
+          ? "Download the current Workit Cursor adapter for the managed local plugin directory"
+          : "Download the Workit Cursor adapter package for the managed local plugin directory",
+        packageRoot: path.join(stage, "node_modules", "@brainervirus", "workit-cursor"),
+        packageTarget: target,
+      },
+    ];
+  }
+  if (host === "opencode") {
+    if (upgrading)
+      throw new Error(
+        "OpenCode CLI cannot target the Workit server plugin for a scoped update; upgrade is unsupported and the current registration was preserved",
+      );
+    // The normal setup path merges this package pin into OpenCode's config;
+    // OpenCode's native resolver installs and refreshes npm plugin packages.
+    return [];
+  }
+  return [];
+}
+
+/** Execute a reviewed plan serially and stop immediately on the first failure. */
+export function runHostInstall(
+  commands: HostInstallCommand[],
+  runner?: HostCommandRunner,
+  context: HostCommandContext = {},
+): {
+  ok: boolean;
+  results: Array<{ command: HostInstallCommand; result: HostCommandResult }>;
+  packageRoot?: string;
+} {
+  const results: Array<{ command: HostInstallCommand; result: HostCommandResult }> = [];
+  let packageRoot: string | undefined;
+  let outputHistory = "";
+  for (const command of commands) {
+    if (command.skipWhenOutputIncludes && outputHistory.includes(command.skipWhenOutputIncludes)) {
+      results.push({
+        command,
+        result: { exitCode: 0, stdout: "", stderr: "already registered; skipped" },
+      });
+      continue;
+    }
+    const result = runner ? runner(command) : runHostCommand(command, context);
+    results.push({ command, result });
+    if (result.exitCode !== 0) return { ok: false, results };
+    outputHistory += `\n${result.stdout}\n${result.stderr}`;
+    if (command.packageRoot && command.packageTarget) {
+      try {
+        if (!existsSync(command.packageRoot)) {
+          return {
+            ok: false,
+            results: [
+              {
+                command,
+                result: {
+                  ...result,
+                  exitCode: 1,
+                  stderr: "npm completed without producing the expected Cursor package",
+                },
+              },
+            ],
+          };
+        } else {
+          packageRoot = command.packageRoot;
+        }
+      } catch (error) {
+        return {
+          ok: false,
+          results: [
+            {
+              command,
+              result: {
+                ...result,
+                exitCode: 1,
+                stderr: error instanceof Error ? error.message : String(error),
+              },
+            },
+          ],
+        };
+      }
+    }
+  }
+  return { ok: true, results, packageRoot };
+}
+
+/** Synchronous, bounded command runner for the synchronous setup Apply API. */
+export function runHostCommand(
+  step: HostInstallCommand,
+  context: HostCommandContext = {},
+): HostCommandResult {
+  if (process.platform === "win32" && /\.(?:cmd|bat)$/i.test(step.command)) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: `Cannot safely execute batch shim ${step.command}; resolve its Node.js CLI entrypoint and retry`,
+    };
+  }
+  const result = spawnSync(step.command, step.args, {
+    cwd: step.cwd,
+    env: (() => {
+      const home = context.home ?? context.env?.HOME ?? os.homedir();
+      const env: NodeJS.ProcessEnv = { ...process.env, ...context.env, HOME: home };
+      env.CODEX_HOME = context.env?.CODEX_HOME ?? path.join(home, ".codex");
+      env.PI_CODING_AGENT_DIR = context.env?.PI_CODING_AGENT_DIR ?? path.join(home, ".pi", "agent");
+      env.XDG_CONFIG_HOME = context.env?.XDG_CONFIG_HOME ?? path.join(home, ".config");
+      return env;
+    })(),
+    encoding: "utf8",
+    timeout: 60_000,
+    windowsHide: true,
+    shell: false,
+  });
+  return {
+    exitCode: result.status ?? (result.error ? 1 : 1),
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? result.error?.message ?? "",
+  };
+}
+
+const findNpmCli = (npm: string): string | null => {
+  const dir = path.dirname(npm);
+  const candidates = [
+    path.join(dir, "node_modules", "npm", "bin", "npm-cli.js"),
+    path.join(dir, "..", "node_modules", "npm", "bin", "npm-cli.js"),
+    path.join(dir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) ?? null;
+};

package/src/core/registration.ts

@@ -31,10 +31,9 @@ export function isWorkitPlugin(value: unknown): boolean {
   const s = String(value).replaceAll("\\", "/");
   const url = s.startsWith("file://") || s.startsWith("git+file://");
   const pkgPath =
-    s.includes("/packages/workit-opencode/") ||
-    s.includes("/packages/workit-cursor/") ||
-    s.includes("/node_modules/@brainervirus/workit-opencode/") ||
-    s.includes("/node_modules/@brainervirus/workit-cursor/");
+    /\/(?:packages\/workit-(?:opencode|cursor)|node_modules\/@brainervirus\/workit-(?:opencode|cursor))(?:\/|$)/.test(
+      s,
+    );
   return (
     named(s, "workflow-toolkit") ||
     named(s, "workflow-toolkit-opencode") ||

package/src/core/setup.ts

@@ -22,6 +22,7 @@ import {
   readConfigFromDir,
   resolveConfigDir,
   type BranchPreset,
+  type ToolkitConfig,
 } from "./config";
 import { detectBranchPolicy } from "./branch-policy";
 import { readSetupState, type SetupState } from "./setup-state";
@@ -38,13 +39,26 @@ import { planHygieneFiles } from "./hygiene";
 import { packageRoot } from "./package-root";
 import {
   cursorMcpServerEntry,
+  CURSOR_RUNTIME_PACKAGE,
+  isWorkitPlugin,
   mergeCursorMcp,
+  mergeOpenCodePlugins,
   mergeCursorSettings,
   mergeOpenCodeConfig,
   OPENCODE_NPM_PIN,
 } from "./registration";
 import { runDoctor, type DoctorReport } from "./doctor";
 import { writeFileExclusive } from "./safe-write";
+import {
+  isCodexWorkitInstalled,
+  isPiWorkitInstalled,
+  planHostInstall,
+  runHostInstall,
+  type HostCommandRunner,
+  type HostId,
+  type HostInstallCommand,
+  runHostCommand,
+} from "./host-install";
 
 // Setup preview + apply (WZ-04-WZ-09, WZ-13-WZ-15; CA-12, CA-14, CA-22, CA-23).
 // buildSetupPreview is a pure reader: it classifies the current setup state and
@@ -82,6 +96,8 @@ export type SetupPreviewInput = {
    *  configured tokenFile, the replacement is planned as its own distinct
    *  reviewed mutation (AR-10). */
   tokenPaths?: { youtrack?: string; gitlab?: string; github?: string };
+  /** Optional global commit policy used as the base for repository overrides. */
+  commitPolicy?: ToolkitConfig["commitPolicy"];
 };
 
 export type SetupMutation =
@@ -98,6 +114,7 @@ export type SetupMutation =
   // during preview so the reviewed mutation set IS the Apply write set.
   | { type: "register-platform"; platform: Platform; path: string }
   | { type: "install-adapter"; platform: "cursor"; path: string }
+  | { type: "install-host"; platform: HostId; path: string; commands: HostInstallCommand[] }
   // AR-10: changing a configured tokenFile path is never hidden inside a
   // generic merge — it is its own reviewed mutation.
   | { type: "set-token-path"; path: string; key: string; value: string };
@@ -249,6 +266,7 @@ export function buildSetupPreview(
         locale: values.locale,
         localeOptions: current.localeOptions,
         timezone: values.timezone,
+        ...(values.commitPolicy === undefined ? {} : { commitPolicy: values.commitPolicy }),
         branchPolicy: mergePreset(
           values.branchPreset,
           {
@@ -344,9 +362,56 @@ export function buildSetupPreview(
         if (platform === "opencode") {
           mutations.push({ type: "register-platform", platform, path: paths.opencodeConfig });
         } else if (platform === "cursor") {
+          const cursorRoot = adapterRoot("cursor", {
+            ...paths,
+            dev: opts.dev ?? env.WORKFLOW_TOOLKIT_DEV ?? null,
+          });
+          if (cursorRoot === null) {
+            const commands = planHostInstall("cursor", {
+              home: paths.home,
+              cwd: paths.cwd,
+              env,
+              packageVersion: "latest",
+              targetDir: paths.cursorPluginDir,
+            });
+            mutations.push({
+              type: "install-host",
+              platform: "cursor",
+              path: path.join(
+                paths.home,
+                ".cursor",
+                "plugins",
+                "local",
+                ".workit-package-bootstrap",
+              ),
+              commands,
+            });
+          }
           mutations.push({ type: "install-adapter", platform, path: paths.cursorPluginDir });
           mutations.push({ type: "register-platform", platform, path: paths.cursorSettings });
           mutations.push({ type: "register-platform", platform, path: paths.cursorMcp });
+        } else if (platform === "codex" || platform === "pi") {
+          const commands = planHostInstall(platform, { home: paths.home, cwd: paths.cwd, env });
+          if (commands.length > 0) {
+            mutations.push({
+              type: "install-host",
+              platform,
+              path:
+                platform === "codex"
+                  ? path.join(
+                      env.CODEX_HOME ?? path.join(paths.home, ".codex"),
+                      "plugins",
+                      "cache",
+                      "workflow-toolkit",
+                      "workit",
+                    )
+                  : path.join(
+                      env.PI_CODING_AGENT_DIR ?? path.join(paths.home, ".pi", "agent"),
+                      "settings.json",
+                    ),
+              commands,
+            });
+          }
         }
       }
     }
@@ -391,7 +456,7 @@ export type Platform = "opencode" | "cursor";
 export type SetupResultStatus = "Installed" | "Configured" | "Skipped" | "Failed";
 
 export type SetupResultEntry = {
-  platform: Platform | "core";
+  platform: HostId | "core";
   file: string;
   status: SetupResultStatus;
   detail?: string;
@@ -422,6 +487,10 @@ export type ApplySetupOptions = {
   cursorMcp?: string;
   cursorPluginDir?: string;
   stateDir?: string;
+  /** Injectable synchronous host runner; defaults to a bounded no-shell spawn. */
+  runHostCommand?: HostCommandRunner;
+  /** Prefer staged npm adapter assets, used by the explicit upgrade flow. */
+  preferInstalledAdapter?: boolean;
 };
 
 type ResolvedApply = {
@@ -528,7 +597,7 @@ const readFileSafe = (p: string): string | null => {
 // adapter resolution (AR-09).
 type CoreMutation = Exclude<
   SetupMutation,
-  { type: "register-platform" } | { type: "install-adapter" }
+  { type: "register-platform" } | { type: "install-adapter" } | { type: "install-host" }
 >;
 
 const workspaceEntriesAlreadyMatch = (
@@ -735,8 +804,23 @@ const isAdapter = (root: string, platform: Platform): boolean => {
   }
 };
 
-function adapterRoot(platform: Platform, res: ResolvedApply): string | null {
+function adapterRoot(
+  platform: Platform,
+  res: ResolvedApply,
+  preferInstalledAdapter = false,
+): string | null {
   const candidates: string[] = [];
+  const stagedCursor = path.join(
+    res.home,
+    ".cursor",
+    "plugins",
+    "local",
+    ".workit-package-bootstrap",
+    "node_modules",
+    "@brainervirus",
+    "workit-cursor",
+  );
+  if (platform === "cursor" && preferInstalledAdapter) candidates.push(stagedCursor);
   if (res.dev) {
     // A dev checkout is the complete source of truth for adapter packages: when
     // WORKFLOW_TOOLKIT_DEV is set, a package missing from it is a real failure,
@@ -757,6 +841,7 @@ function adapterRoot(platform: Platform, res: ResolvedApply): string | null {
   candidates.push(
     path.join(res.home, ".local", "share", "workit", "packages", `workit-${platform}`),
   );
+  if (platform === "cursor") candidates.push(stagedCursor);
   for (const candidate of candidates) {
     if (isAdapter(candidate, platform)) return candidate;
   }
@@ -787,8 +872,8 @@ const opencodePin = (root: string, res: ResolvedApply): string | null =>
   resolveOpenCodePin(root, { dev: res.dev });
 
 function applyOpenCode(root: string, res: ResolvedApply): SetupResultEntry {
-  const pin = opencodePin(root, res);
-  if (!pin) {
+  const resolvedPin = opencodePin(root, res);
+  if (!resolvedPin) {
     return {
       platform: "opencode",
       file: res.opencodeConfig,
@@ -807,7 +892,33 @@ function applyOpenCode(root: string, res: ResolvedApply): SetupResultEntry {
       detail: `cannot merge into malformed config: ${existing.error} — repair or remove the file`,
     };
   }
-  const merged = mergeOpenCodeConfig(existing.kind === "record" ? existing.value : {}, pin);
+  const configuredPlugins =
+    existing.kind === "record"
+      ? Array.isArray(existing.value.plugins)
+        ? existing.value.plugins
+        : typeof existing.value.plugins === "string"
+          ? [existing.value.plugins]
+          : typeof existing.value.plugin === "string"
+            ? [existing.value.plugin]
+            : Array.isArray(existing.value.plugin)
+              ? existing.value.plugin
+              : []
+      : [];
+  const configuredPin = configuredPlugins.find(
+    (entry): entry is string => typeof entry === "string" && isWorkitPlugin(entry),
+  );
+  const pin = configuredPin ?? resolvedPin;
+  const base = existing.kind === "record" ? existing.value : {};
+  const merged =
+    existing.kind === "record" && Object.hasOwn(existing.value, "plugins")
+      ? (() => {
+          const plugins = mergeOpenCodePlugins(existing.value.plugins, pin);
+          return {
+            config: { ...existing.value, plugins: plugins.config },
+            changed: plugins.changed.length > 0 ? ["plugins"] : [],
+          };
+        })()
+      : mergeOpenCodeConfig(base, pin);
   if (merged.changed.length === 0) {
     return {
       platform: "opencode",
@@ -996,11 +1107,21 @@ function applyCursorMcp(root: string, res: ResolvedApply): SetupResultEntry {
       detail: `cannot merge into malformed config: ${mcpExisting.error} — repair or remove the file`,
     };
   }
-  const mcp = mergeCursorMcp(
-    mcpExisting.kind === "record" ? mcpExisting.value : {},
-    "workit",
-    cursorMcpServerEntry(res.cursorPluginDir),
+  const mcpBase = mcpExisting.kind === "record" ? mcpExisting.value : {};
+  const server = cursorMcpServerEntry(res.cursorPluginDir);
+  const servers = isRecord(mcpBase.mcpServers) ? mcpBase.mcpServers : {};
+  const current = isRecord(servers.workit) ? servers.workit : {};
+  const previousArgs = Array.isArray(current.args) ? current.args.map(String) : [];
+  const previousPackage = previousArgs.find(
+    (arg) =>
+      arg.startsWith("--package=@brainervirus/workit-cursor@") &&
+      arg !== `--package=${CURSOR_RUNTIME_PACKAGE}`,
   );
+  if (previousPackage) {
+    const index = server.args.findIndex((arg) => arg.startsWith("--package="));
+    if (index >= 0) server.args[index] = previousPackage;
+  }
+  const mcp = mergeCursorMcp(mcpBase, "workit", server);
   if (mcp.changed.length === 0) {
     return {
       platform: "cursor",
@@ -1117,6 +1238,77 @@ export function applySetupPreview(
   // legacy identity or its registration.
   let cursorCopyOk = false;
   for (const mutation of preview.mutations) {
+    if (mutation.type === "install-host") {
+      const expectedPath =
+        mutation.platform === "cursor"
+          ? path.join(res.home, ".cursor", "plugins", "local", ".workit-package-bootstrap")
+          : mutation.platform === "codex"
+            ? path.join(
+                res.env.CODEX_HOME ?? path.join(res.home, ".codex"),
+                "plugins",
+                "cache",
+                "workflow-toolkit",
+                "workit",
+              )
+            : mutation.platform === "pi"
+              ? path.join(
+                  res.env.PI_CODING_AGENT_DIR ?? path.join(res.home, ".pi", "agent"),
+                  "settings.json",
+                )
+              : "";
+      if (mutation.path !== expectedPath) {
+        entries.push({
+          platform: mutation.platform,
+          file: mutation.path,
+          status: "Failed",
+          detail: `preview/apply path mismatch: apply resolved ${expectedPath}, the previewed host install was ${mutation.path} — rebuild the preview with the same options`,
+        });
+        continue;
+      }
+      const run =
+        options.runHostCommand ??
+        ((step: HostInstallCommand) => runHostCommand(step, { home: res.home, env: res.env }));
+      const installed = runHostInstall(mutation.commands, run);
+      for (const { command, result } of installed.results) {
+        entries.push({
+          platform: mutation.platform,
+          file: command.command,
+          status: result.exitCode === 0 ? "Installed" : "Failed",
+          detail:
+            result.exitCode === 0
+              ? `${command.purpose} (${command.args.join(" ")})`
+              : `${command.purpose} failed (${command.args.join(" ")}): ${result.stderr || `exit ${result.exitCode}`}`,
+        });
+      }
+      if (!installed.ok && installed.results.length === 0) {
+        entries.push({
+          platform: mutation.platform,
+          file: mutation.platform,
+          status: "Failed",
+          detail: "host installation did not run",
+        });
+      }
+      if (!installed.ok) continue;
+      if (mutation.platform === "cursor" && installed.packageRoot) {
+        rootFor.set("cursor", installed.packageRoot);
+      }
+      const verified =
+        mutation.platform === "codex"
+          ? isCodexWorkitInstalled(res.home, res.env)
+          : mutation.platform === "pi"
+            ? isPiWorkitInstalled(res.home, res.env)
+            : true;
+      if (!verified) {
+        entries.push({
+          platform: mutation.platform,
+          file: mutation.platform,
+          status: "Failed",
+          detail:
+            "the host command succeeded, but Workit registration was not found; inspect the host's native package list and retry",
+        });
+      }
+      continue;
+    }
     if (mutation.type !== "register-platform" && mutation.type !== "install-adapter") {
       entries.push(applyMutation(mutation));
       continue;
@@ -1141,7 +1333,7 @@ export function applySetupPreview(
     }
     let root = rootFor.get(platform);
     if (root === undefined) {
-      root = adapterRoot(platform, res);
+      root = adapterRoot(platform, res, options.preferInstalledAdapter);
       rootFor.set(platform, root);
     }
     if (root === null) {

package/src/core/vcs-config.ts

@@ -191,10 +191,8 @@ export function vcsConfig(mode: "load" | "summary" | "resolve", cwd?: string): R
       (hasWorkspacePolicy ? policyDefault : (cfg.defaultTargetBranch ?? policyDefault)) ??
       "develop",
   );
-  const linkIssues =
-    provider === "gitlab" && typeof wsYt.link_issues === "boolean" ? wsYt.link_issues : null;
-  const youtrackBaseUrl =
-    provider === "gitlab" && typeof wsYt.baseUrl === "string" ? wsYt.baseUrl : null;
+  const linkIssues = typeof wsYt.link_issues === "boolean" ? wsYt.link_issues : null;
+  const youtrackBaseUrl = typeof wsYt.baseUrl === "string" ? wsYt.baseUrl : null;
   // github issues path only when BOTH providers are github (mirrors WorkspaceConfig.issues).
   let issuesProvider: string | null = null;
   let linkOnPr: boolean | null = null;

package/src/core/workspaces.ts

@@ -134,13 +134,6 @@ const workspaceConfigSchema = z
   })
   .passthrough()
   .superRefine((workspace, context) => {
-    if (workspace.youtrack && workspace.vcs?.provider !== "gitlab") {
-      context.addIssue({
-        code: "custom",
-        path: ["youtrack"],
-        message: `YouTrack issue linking requires the gitlab provider, got ${workspace.vcs?.provider ?? "unset"}`,
-      });
-    }
     if (workspace.issues && workspace.vcs?.provider !== "github") {
       context.addIssue({
         code: "custom",
@@ -446,23 +439,21 @@ const selectWorkspaceMatch = <T extends { name: string; glob: string }>(
   return mostSpecific[0];
 };
 
-/** Match a cwd against the workspaces.json under an explicit config dir. */
-export const resolveWorkspaceFrom = (
+/** Shared pure workspace matcher for draft previews and disk-backed resolution. */
+export const resolveWorkspaceFromEntries = <T extends { name: string; glob: string }>(
   cwd: string,
-  dir: string,
+  entries: readonly T[],
   workspaceName?: string,
-): WorkspaceConfig | null => {
+): T | null => {
   // macOS/Windows tmpdir symlinks (/var -> /private/var): git's
   // --show-toplevel returns the realpath while config globs are usually
   // written with the logical path, so a workspace would silently stop
   // matching on macOS. Match both forms on each side — same class as the
   // docs-migration escape-guard realpath comparison; on Linux both forms
   // are identical so behavior is unchanged.
-  const result = readWorkspacesResult(dir);
-  if (result.status === "malformed" || result.status === "invalid") throw new Error(result.error);
   const targets = [cwd, realpathOf(cwd)].map((p) => p.replaceAll("\\", "/"));
-  const matches: WorkspaceConfig[] = [];
-  for (const ws of result.entries) {
+  const matches: T[] = [];
+  for (const ws of entries) {
     const glob = ws.glob.replaceAll("\\", "/");
     const canonical = canonicalGlob(glob);
     let matched = false;
@@ -480,6 +471,17 @@ export const resolveWorkspaceFrom = (
   return selectWorkspaceMatch(matches, cwd, workspaceName) ?? null;
 };
 
+/** Match a cwd against the workspaces.json under an explicit config dir. */
+export const resolveWorkspaceFrom = (
+  cwd: string,
+  dir: string,
+  workspaceName?: string,
+): WorkspaceConfig | null => {
+  const result = readWorkspacesResult(dir);
+  if (result.status === "malformed" || result.status === "invalid") throw new Error(result.error);
+  return resolveWorkspaceFromEntries(cwd, result.entries, workspaceName);
+};
+
 export const resolveWorkspace = (
   cwd: string,
   workspaceName = process.env.WORKFLOW_WORKSPACE_NAME?.trim() || undefined,