fix(vcs): report unsupported initialization as 501

packages/app/e2e/regression/review-no-git.spec.ts

@@ -0,0 +1,68 @@
+import { base64Encode } from "@opencode/util/encode"
+import { expect, test } from "@playwright/test"
+import { mockOpenCodeServer } from "../utils/mock-server"
+import { expectSessionTitle } from "../utils/waits"
+
+const directory = "C:/OpenCode/ReviewWithoutGit"
+const sessionID = "ses_review_without_git"
+const server = `http://${process.env.PLAYWRIGHT_SERVER_HOST ?? "127.0.0.1"}:${process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"}`
+
+for (const view of ["desktop", "mobile"] as const) {
+  test(`offers Git initialization instead of an empty changes selector (${view})`, async ({ page }) => {
+    test.setTimeout(180_000)
+    if (view === "mobile") await page.setViewportSize({ width: 390, height: 844 })
+    const project = {
+      id: "proj_review_without_git",
+      worktree: directory,
+      vcs: undefined as string | undefined,
+      name: "review-without-git",
+      time: { created: 1700000000000, updated: 1700000000000 },
+      sandboxes: [],
+    }
+    const session = {
+      id: sessionID,
+      slug: sessionID,
+      projectID: project.id,
+      directory,
+      title: "Review without Git",
+      version: "dev",
+      time: { created: 1700000000000, updated: 1700000000000 },
+    }
+    await mockOpenCodeServer(page, {
+      directory,
+      project,
+      provider: { all: [], connected: [], default: {} },
+      sessions: [session],
+      pageMessages: () => ({ items: [] }),
+    })
+    const requests: string[] = []
+    await page.route("**/api/vcs/init*", (route) => {
+      requests.push(route.request().url())
+      project.id = "proj_review_with_git"
+      project.vcs = "git"
+      session.projectID = project.id
+      return route.fulfill({ status: 204 })
+    })
+    await page.goto(`/server/${base64Encode(server)}/session/${sessionID}`, { waitUntil: "domcontentloaded" })
+    if (view === "desktop") {
+      await expectSessionTitle(page, "Review without Git")
+      await page.getByRole("button", { name: "Toggle review" }).click()
+    } else {
+      await page.getByRole("tablist", { name: "Session view" }).getByRole("tab", { name: "Changes" }).click()
+    }
+
+    const panel = view === "desktop" ? page.locator("#review-panel") : page.locator("[data-component='session-review']")
+    await expect(panel.getByText("Track, review, and undo changes in this project")).toBeVisible()
+    await expect(panel.getByRole("button", { name: "Git changes" })).toHaveCount(0)
+    const init = panel.getByRole("button", { name: "Create Git repository" })
+    await expect(init).toBeVisible()
+    await test.info().attach("review-without-git", { body: await panel.screenshot(), contentType: "image/png" })
+    await init.click()
+    await expect(panel.getByRole("button", { name: "Git changes" })).toBeVisible()
+    await expect(init).toHaveCount(0)
+    await test.info().attach("review-after-git", { body: await panel.screenshot(), contentType: "image/png" })
+    expect(requests).toHaveLength(1)
+    expect(new URL(requests[0]!).searchParams.get("location[directory]")).toBe(directory)
+    expect(new URL(requests[0]!).searchParams.get("provider")).toBe("git")
+  })
+}

packages/app/src/session/review/model.ts

@@ -17,6 +17,8 @@ import { createOpenReviewFile } from "../helpers"
 import type { SessionModel } from "../model"
 import type { SessionScreenLayout } from "../screen-layout"
 import { createReviewPanelState } from "./panel-state"
+import { showToast } from "@/shell/notifications/toast"
+import { formatServerError } from "@/runtime/server/errors"
 import { reviewDiffDirectory, reviewDiffNeedsLoad, reviewRootDirectory } from "./review-diff-kinds"
 import type { DiffStyle } from "./review-tab"
 
@@ -42,6 +44,7 @@ export function createSessionReview(input: {
     detailsOpen: false,
     scroll: undefined as HTMLDivElement | undefined,
     pendingFile: undefined as string | undefined,
+    initializingGit: false,
   })
   const mode = () => input.session.layout.view().review.mode() ?? "git"
   const selectedFile = () => input.session.layout.view().review.file()
@@ -161,6 +164,32 @@ export function createSessionReview(input: {
     if (mode() === "git" || mode() === "branch") return !vcsQuery.isPending
     return true
   }
+  const initializeGit = () => {
+    if (state.initializingGit) return
+    const directory = location().directory
+    const sessionID = input.session.identity.params.id
+    if (!sessionID) return
+    setState("initializingGit", true)
+    void server.api.vcs
+      .init({ location: { directory }, provider: "git" })
+      .then(async () => {
+        data.project.invalidate()
+        data.session.invalidate(sessionID)
+        data.location.invalidate({ directory })
+        data.location.vcs.invalidate({ directory })
+        await data.project.sync()
+        await data.session.sync(sessionID)
+        await Promise.all([data.location.sync({ directory }), data.location.vcs.sync({ directory })])
+      })
+      .catch((error) =>
+        showToast({
+          variant: "error",
+          title: language.t("common.requestFailed"),
+          description: formatServerError(error, language.t),
+        }),
+      )
+      .finally(() => setState("initializingGit", false))
+  }
   const loadDiff = async (path: string, version?: number): Promise<FileDiffInfo | undefined> => {
     const value = vcsMode()
     if (!value) return undefined
@@ -410,6 +439,8 @@ export function createSessionReview(input: {
     diffs,
     focusFile,
     hasChanges,
+    initializeGit,
+    initializingGit: () => state.initializingGit,
     loadDiff,
     mobile: {
       changes: mobileChanges,

packages/app/src/session/review/view.tsx

@@ -1,4 +1,5 @@
 import { SessionReviewEmptyChangesV2 } from "@opencode/session-ui/v2/session-review-empty-changes-v2"
+import { SessionReviewEmptyNoGitV2 } from "@opencode/session-ui/v2/session-review-empty-no-git-v2"
 import { SessionReviewV2SidebarToggle } from "@opencode/session-ui/v2/session-review-v2"
 import { Select } from "@opencode/ui/select"
 import { Tabs } from "@opencode/ui/tabs"
@@ -237,7 +238,7 @@ function ReviewTitle(props: { review: SessionReviewModel }) {
     return language.t("ui.sessionReview.title.lastTurn")
   }
   return (
-    <Show when={props.review.canReview()}>
+    <Show when={props.review.canReview() && props.review.options().length > 0}>
       <Select
         options={props.review.options()}
         current={props.review.mode()}
@@ -253,7 +254,6 @@ function ReviewTitle(props: { review: SessionReviewModel }) {
 function ReviewEmpty(props: { review: SessionReviewModel; loadingClass: string }) {
   const language = useLanguage()
   const loading = () => (props.review.mode() === "git" || props.review.mode() === "branch") && !props.review.ready()
-  const noGit = () => props.review.noGit()
   const text = () => {
     if (props.review.mode() === "git") return language.t("session.review.noUncommittedChanges")
     if (props.review.mode() === "branch") return language.t("session.review.noBranchChanges")
@@ -264,14 +264,9 @@ function ReviewEmpty(props: { review: SessionReviewModel; loadingClass: string }
       <Match when={loading()}>
         <div class={props.loadingClass}>{language.t("session.review.loadingChanges")}</div>
       </Match>
-      <Match when={noGit()}>
-        <div class="h-full pb-64 -mt-4 flex flex-col items-center justify-center text-center gap-6">
-          <div class="flex flex-col gap-3">
-            <div class="text-14-medium text-text-strong">{language.t("session.review.noVcs.createGit.title")}</div>
-            <div class="text-14-regular text-text-base max-w-md" style={{ "line-height": "var(--line-height-normal)" }}>
-              {language.t("session.review.noVcs.createGit.description")}
-            </div>
-          </div>
+      <Match when={props.review.noGit()}>
+        <div class="h-full flex flex-col">
+          <SessionReviewEmptyNoGitV2 pending={props.review.initializingGit()} onInitGit={props.review.initializeGit} />
         </div>
       </Match>
       <Match when={true}>
@@ -286,18 +281,13 @@ function ReviewEmpty(props: { review: SessionReviewModel; loadingClass: string }
 function ReviewPanelEmpty(props: { review: SessionReviewModel }) {
   const language = useLanguage()
   const loading = () => (props.review.mode() === "git" || props.review.mode() === "branch") && !props.review.ready()
-  const noGit = () => props.review.noGit()
   return (
     <Switch>
       <Match when={loading()}>
         <div class="px-6 py-4 text-text-weak">{language.t("session.review.loadingChanges")}</div>
       </Match>
-      <Match when={noGit()}>
-        <div class="h-full pb-64 -mt-4 flex flex-col items-center justify-center text-center gap-6">
-          <div class="text-14-regular text-text-weak max-w-56">
-            {language.t("session.review.noVcs.createGit.description")}
-          </div>
-        </div>
+      <Match when={props.review.noGit()}>
+        <SessionReviewEmptyNoGitV2 pending={props.review.initializingGit()} onInitGit={props.review.initializeGit} />
       </Match>
       <Match when={true}>
         <SessionReviewEmptyChangesV2 />

packages/client/src/effect/api/api.ts

@@ -2223,6 +2223,13 @@ export interface WorktreeApi<E = never> {
   readonly refresh: WorktreeRefreshOperation<E>
 }
 
+export type VcsInitInput = {
+  readonly location?: { readonly directory?: string | undefined } | undefined
+  readonly provider?: string | undefined
+}
+export type VcsInitOutput = void
+export type VcsInitOperation<E = never> = (input?: VcsInitInput) => Effect.Effect<VcsInitOutput, E>
+
 export type VcsGetInput = { readonly location?: { readonly directory?: string | undefined } | undefined }
 export type VcsGetOutput = { readonly location: Location.PublicRef; readonly data: Vcs.Info }
 export type VcsGetOperation<E = never> = (input?: VcsGetInput) => Effect.Effect<VcsGetOutput, E>
@@ -2253,6 +2260,7 @@ export type VcsDiffOutput = { readonly location: Location.PublicRef; readonly da
 export type VcsDiffOperation<E = never> = (input: VcsDiffInput) => Effect.Effect<VcsDiffOutput, E>
 
 export interface VcsApi<E = never> {
+  readonly init: VcsInitOperation<E>
   readonly get: VcsGetOperation<E>
   readonly base: VcsBaseOperation<E>
   readonly status: VcsStatusOperation<E>

packages/client/src/effect/generated/client.ts

@@ -239,6 +239,8 @@ import type {
   WorktreeRemoveOutput,
   WorktreeRefreshInput,
   WorktreeRefreshOutput,
+  VcsInitInput,
+  VcsInitOutput,
   VcsGetInput,
   VcsGetOutput,
   VcsBaseInput,
@@ -1450,6 +1452,13 @@ const adaptGroupWorktree = (raw: RawClient["server.worktree"]) => ({
   refresh: EndpointWorktreeRefresh(raw),
 })
 
+const EndpointVcsInit = (raw: RawClient["server.vcs"]) => (input?: VcsInitInput) =>
+  preserveEffect<VcsInitOutput>()(
+    raw["vcs.init"]({ query: { location: input?.["location"], provider: input?.["provider"] } }).pipe(
+      Effect.mapError(mapClientError),
+    ),
+  )
+
 const EndpointVcsGet = (raw: RawClient["server.vcs"]) => (input?: VcsGetInput) =>
   preserveEffect<VcsGetOutput>()(
     raw["vcs.get"]({ query: { location: input?.["location"] } }).pipe(Effect.mapError(mapClientError)),
@@ -1480,6 +1489,7 @@ const EndpointVcsDiff = (raw: RawClient["server.vcs"]) => (input: VcsDiffInput)
   )
 
 const adaptGroupVcs = (raw: RawClient["server.vcs"]) => ({
+  init: EndpointVcsInit(raw),
   get: EndpointVcsGet(raw),
   base: EndpointVcsBase(raw),
   status: EndpointVcsStatus(raw),

packages/client/src/promise/generated/client.ts

@@ -237,6 +237,8 @@ import type {
   WorktreeRemoveOutput,
   WorktreeRefreshInput,
   WorktreeRefreshOutput,
+  VcsInitInput,
+  VcsInitOutput,
   VcsGetInput,
   VcsGetOutput,
   VcsBaseInput,
@@ -2012,6 +2014,18 @@ export function make(options: ClientOptions) {
         ),
     },
     vcs: {
+      init: (input?: VcsInitInput, requestOptions?: RequestOptions) =>
+        request<VcsInitOutput>(
+          {
+            method: "POST",
+            path: `/api/vcs/init`,
+            query: { location: input?.["location"], provider: input?.["provider"] },
+            successStatus: 204,
+            declaredStatuses: [400, 401, 409, 501, 503],
+            empty: true,
+          },
+          requestOptions,
+        ),
       get: (input?: VcsGetInput, requestOptions?: RequestOptions) =>
         request<VcsGetOutput>(
           {

packages/client/src/promise/generated/types.ts

@@ -2700,6 +2700,14 @@ export type WorktreeError = {
 export const isWorktreeError = (value: unknown): value is WorktreeError =>
   typeof value === "object" && value !== null && "name" in value && value["name"] === "WorktreeError"
 
+export type VcsInitNotSupportedError = {
+  readonly _tag: "VcsInitNotSupportedError"
+  readonly providerID: string
+  readonly message: string
+}
+export const isVcsInitNotSupportedError = (value: unknown): value is VcsInitNotSupportedError =>
+  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "VcsInitNotSupportedError"
+
 export type ServerInfoOutput = ServerInfo
 
 export type ServerPairOutput = PairingCode
@@ -6249,6 +6257,19 @@ export type WorktreeRefreshInput = { readonly projectID: { readonly projectID: s
 
 export type WorktreeRefreshOutput = void
 
+export type VcsInitInput = {
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined } | undefined
+    readonly provider?: string | undefined
+  }["location"]
+  readonly provider?: {
+    readonly location?: { readonly directory?: string | undefined } | undefined
+    readonly provider?: string | undefined
+  }["provider"]
+}
+
+export type VcsInitOutput = void
+
 export type VcsGetInput = {
   readonly location?: { readonly location?: { readonly directory?: string | undefined } | undefined }["location"]
 }

packages/core/src/plugin/vcs/git.ts

@@ -23,7 +23,8 @@ export const Plugin = define({
   id: "opencode.vcs.git",
   effect: Effect.fn("VcsGitPlugin")(function* (ctx) {
     const location = yield* Location.Service
-    if (location.vcs?.type !== "git") return
+    // Markerless locations need this definition to initialize their first repository.
+    if (location.vcs && location.vcs.type !== "git") return
 
     const processes = yield* AppProcess.Service
     const adapter = make(processes, {
@@ -35,6 +36,13 @@ export const Plugin = define({
       editor.add({
         id: "git",
         name: "Git",
+        init: (input) =>
+          Effect.gen(function* () {
+            const result = yield* processes.run(
+              ChildProcess.make(gitExecutable, ["init"], { cwd: input.worktree, stdin: "ignore" }),
+            )
+            if (result.exitCode !== 0) return yield* Effect.fail(new Error("Git initialization failed"))
+          }),
         info: () => adapter.info(),
         base: () => adapter.base(),
         branches: (input) => adapter.branches({ search: input.search, limit: input.limit }),

packages/core/src/plugin/vcs/hg.ts

@@ -26,7 +26,8 @@ export const Plugin = define({
   id: "opencode.vcs.hg",
   effect: Effect.fn("VcsHgPlugin")(function* (ctx) {
     const location = yield* Location.Service
-    if (location.vcs?.type !== "hg") return
+    // Markerless locations need this definition to initialize their first repository.
+    if (location.vcs && location.vcs.type !== "hg") return
 
     const processes = yield* AppProcess.Service
     const fs = yield* FSUtil.Service
@@ -39,6 +40,18 @@ export const Plugin = define({
       editor.add({
         id: "hg",
         name: "Mercurial",
+        init: (input) =>
+          Effect.gen(function* () {
+            const result = yield* processes.run(
+              ChildProcess.make("hg", ["init"], {
+                cwd: input.worktree,
+                env: { HGPLAIN: "1" },
+                extendEnv: true,
+                stdin: "ignore",
+              }),
+            )
+            if (result.exitCode !== 0) return yield* Effect.fail(new Error("Mercurial initialization failed"))
+          }),
         info: () => adapter.info(),
         branches: (input) => adapter.branches({ search: input.search, limit: input.limit }),
         status: () => adapter.status(),

packages/core/src/vcs.ts

@@ -10,6 +10,7 @@ import { VcsEvent } from "@opencode/schema/vcs-event"
 import { makeLocationNode } from "@opencode/util/effect/app-node"
 import { FSUtil } from "@opencode/util/fs-util"
 import { Location } from "./location.js"
+import { Project } from "./project.js"
 import { Bus } from "./bus.js"
 import { State } from "./state.js"
 import { emptyPatch, MAX_TOTAL_PATCH_BYTES, PATCH_CONTEXT_LINES } from "./vcs/patch.js"
@@ -20,6 +21,10 @@ export class DiffError extends Schema.TaggedError<DiffError>()("Vcs.DiffError",
   message: Schema.String,
 }) {}
 
+export class InitializeError extends Schema.TaggedError<InitializeError>()("Vcs.InitializeError", {
+  kind: Schema.Literals(["missing", "conflict", "unknown", "unsupported", "failed"]),
+}) {}
+
 export interface DiffOptions {
   readonly context?: number
   readonly base?: string
@@ -40,6 +45,7 @@ export interface Adapter {
 
 export interface Interface extends Adapter, State.Transformable<VcsEditor> {
   readonly base: () => Effect.Effect<Base | null, DiffError>
+  readonly initialize: (providerID: string) => Effect.Effect<void, InitializeError>
 }
 
 interface Data {
@@ -124,7 +130,9 @@ const layer = Layer.effect(
         const provider = selected()
         const next: Info = provider
           ? {
-              ...(yield* protect(provider, "info", provider.info(scope).pipe(Effect.flatMap(decodeInfo)), { branch: {} })),
+              ...(yield* protect(provider, "info", provider.info(scope).pipe(Effect.flatMap(decodeInfo)), {
+                branch: {},
+              })),
               provider: provider.id,
             }
           : { branch: {} }
@@ -166,6 +174,24 @@ const layer = Layer.effect(
     return Service.of({
       transform: state.transform,
       reload: state.reload,
+      initialize: Effect.fn("Vcs.initialize")(function* (providerID: string) {
+        if (!(yield* fs.isDir(location.project.directory))) return yield* new InitializeError({ kind: "missing" })
+        if (yield* Project.root(fs, location.project.directory)) return yield* new InitializeError({ kind: "conflict" })
+        const provider = state.get().providers.get(providerID)
+        if (!provider) return yield* new InitializeError({ kind: "unknown" })
+        if (!provider.init) return yield* new InitializeError({ kind: "unsupported" })
+        yield* provider
+          .init(scope)
+          .pipe(
+            Effect.catchCause((cause) =>
+              Cause.hasInterrupts(cause)
+                ? Effect.failCause(cause).pipe(Effect.orDie)
+                : Effect.logWarning("vcs initialization failed", { provider: providerID, cause }).pipe(
+                    Effect.andThen(Effect.fail(new InitializeError({ kind: "failed" }))),
+                  ),
+            ),
+          )
+      }),
       info: Effect.fn("Vcs.info")(function* () {
         return current.info
       }),

packages/core/test/plugin/vcs-init.test.ts

@@ -0,0 +1,48 @@
+import { expect } from "bun:test"
+import { Plugin } from "@opencode/plugin"
+import type { VcsDefinition } from "@opencode/plugin/effect/vcs"
+import { PluginPromise } from "@opencode/core/plugin/promise"
+import { State } from "@opencode/core/state"
+import { Effect } from "effect"
+import { it } from "../lib/effect"
+import { host } from "./host"
+
+it.live("Promise VCS initializer reaches the registered provider with its location scope", () =>
+  Effect.gen(function* () {
+    const calls: string[] = []
+    const state = State.create({
+      initial: () => new Map<string, VcsDefinition>(),
+      editor: (providers) => ({
+        add: (definition: VcsDefinition) => providers.set(definition.id, definition),
+        default: { get: () => undefined, set: (_selection: string) => {} },
+      }),
+    })
+    const context = host()
+    const plugin = PluginPromise.fromPromise(
+      Plugin.define({
+        id: "init-vcs",
+        async setup(ctx) {
+          await ctx.vcs.transform((editor) =>
+            editor.add({
+              id: "custom",
+              name: "Custom VCS",
+              init: async (scope, { signal }) => {
+                expect(signal.aborted).toBe(false)
+                calls.push(scope.worktree)
+              },
+              info: async () => ({ branch: {} }),
+              branches: async () => [],
+              status: async () => [],
+              diff: async () => [],
+            }),
+          )
+        },
+      }),
+    )
+    yield* plugin.effect(host({ vcs: { ...context.vcs, transform: state.transform, reload: state.reload } }))
+    const init = state.get().get("custom")?.init
+    if (!init) return yield* Effect.die("Initializer was not registered")
+    yield* init({ directory: "/workspace", worktree: "/workspace", canonical: "/workspace" })
+    expect(calls).toEqual(["/workspace"])
+  }),
+)

packages/core/test/vcs.test.ts

@@ -103,6 +103,29 @@ const provider = (input: Partial<VcsDefinition> = {}) =>
   }) satisfies VcsDefinition
 
 describe("Vcs", () => {
+  it.live("routes initialization through the requested provider before a repository exists", () =>
+    withTmp((directory) =>
+      Effect.gen(function* () {
+        const vcs = yield* Vcs.Service
+        const calls: string[] = []
+        yield* vcs.transform((editor) => {
+          editor.add(provider({ id: "read-only" }))
+          editor.add(
+            provider({
+              id: "custom",
+              init: (input) => Effect.sync(() => void calls.push(input.worktree)),
+            }),
+          )
+        })
+        expect(yield* vcs.initialize("missing").pipe(Effect.flip)).toMatchObject({ kind: "unknown" })
+        expect(yield* vcs.initialize("read-only").pipe(Effect.flip)).toMatchObject({ kind: "unsupported" })
+        expect(calls).toEqual([])
+        yield* vcs.initialize("custom")
+        expect(calls).toEqual([directory])
+      }).pipe(provide(directory)),
+    ),
+  )
+
   it.live("returns empty results outside version control", () =>
     withTmp((directory) =>
       Effect.gen(function* () {

packages/plugin/src/effect/vcs.ts

@@ -26,6 +26,7 @@ export interface VcsDiffInput extends VcsScope {
 export interface VcsDefinition {
   readonly id: string
   readonly name: string
+  readonly init?: (input: VcsScope) => Effect.Effect<void, unknown>
   readonly info: (input: VcsScope) => Effect.Effect<Vcs.Info, unknown>
   readonly base?: (input: VcsScope) => Effect.Effect<Vcs.Base | null, unknown>
   readonly branches: (input: VcsBranchesInput) => Effect.Effect<Vcs.BranchList, unknown>
@@ -33,7 +34,7 @@ export interface VcsDefinition {
   readonly diff: (input: VcsDiffInput) => Effect.Effect<readonly FileDiff.Info[], unknown>
 }
 
-export interface VcsDomain extends VcsApi<unknown> {
+export interface VcsDomain extends Omit<VcsApi<unknown>, "init"> {
   readonly transform: Transform<VcsEditor>
   readonly reload: () => Effect.Effect<void>
 }

packages/plugin/src/promise/adapter.ts

@@ -517,10 +517,12 @@ export function fromPromise(plugin: Plugin) {
                 host.vcs.transform((editor) => {
                   callback({
                     add: (definition) => {
+                      const init = definition.init?.bind(definition)
                       const base = definition.base?.bind(definition)
                       editor.add({
                         id: definition.id,
                         name: definition.name,
+                        init: init ? (input) => attempt((signal) => init(input, { signal })) : undefined,
                         info: (input) => attempt((signal) => definition.info(input, { signal })),
                         base: base ? (input) => attempt((signal) => base(input, { signal })) : undefined,
                         branches: (input) => attempt((signal) => definition.branches(input, { signal })),

packages/plugin/src/promise/vcs.ts

@@ -25,6 +25,7 @@ export interface VcsDiffInput extends VcsScope {
 export interface VcsDefinition {
   readonly id: string
   readonly name: string
+  readonly init?: (input: VcsScope, context: { readonly signal: AbortSignal }) => Promise<void>
   readonly info: (input: VcsScope, context: { readonly signal: AbortSignal }) => Promise<Vcs.Info>
   readonly base?: (input: VcsScope, context: { readonly signal: AbortSignal }) => Promise<Vcs.Base | null>
   readonly branches: (input: VcsBranchesInput, context: { readonly signal: AbortSignal }) => Promise<Vcs.BranchList>
@@ -32,7 +33,7 @@ export interface VcsDefinition {
   readonly diff: (input: VcsDiffInput, context: { readonly signal: AbortSignal }) => Promise<readonly FileDiff.Info[]>
 }
 
-export interface VcsDomain extends VcsApi {
+export interface VcsDomain extends Omit<VcsApi, "init"> {
   readonly transform: Transform<VcsEditor>
   readonly reload: () => Promise<void>
 }

packages/protocol/src/groups/vcs.ts

@@ -3,9 +3,20 @@ import { Location } from "@opencode/schema/location"
 import { NonNegativeInt, PositiveInt, optional } from "@opencode/schema/schema"
 import { Vcs } from "@opencode/schema/vcs"
 import { Schema } from "effect"
-import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
 import { LocationQuery, locationQueryOpenApi } from "./location.js"
-import { ServiceUnavailableError } from "../errors.js"
+import { ConflictError, InvalidRequestError, ServiceUnavailableError } from "../errors.js"
+
+const InitQuery = Schema.Struct({
+  ...LocationQuery.fields,
+  provider: Schema.optional(Schema.String),
+})
+
+export class VcsInitNotSupportedError extends Schema.TaggedError<VcsInitNotSupportedError>()(
+  "VcsInitNotSupportedError",
+  { providerID: Schema.String, message: Schema.String },
+  { httpApiStatus: 501 },
+) {}
 
 const BranchesQuery = Schema.Struct({
   ...LocationQuery.fields,
@@ -21,6 +32,22 @@ const DiffQuery = Schema.Struct({
 })
 
 export const VcsGroup = HttpApiGroup.make("server.vcs")
+  .add(
+    HttpApiEndpoint.post("vcs.init", "/api/vcs/init", {
+      query: InitQuery,
+      success: HttpApiSchema.NoContent,
+      error: [ConflictError, InvalidRequestError, VcsInitNotSupportedError, ServiceUnavailableError],
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "vcs.init",
+          summary: "Initialize VCS repository",
+          description:
+            "Initialize a repository using the selected VCS provider in a markerless project's directory and refresh its location services. Omitting provider defaults to git; built-in git and hg providers support initialization. An unknown provider returns 400; a registered provider without init returns 501.",
+        }),
+      ),
+  )
   .add(
     HttpApiEndpoint.get("vcs.get", "/api/vcs", {
       query: LocationQuery,

packages/server/src/handlers/vcs.ts

@@ -1,13 +1,54 @@
 import { Vcs } from "@opencode/core/vcs"
-import { ServiceUnavailableError } from "@opencode/protocol/errors"
+import { Project } from "@opencode/core/project"
+import { Plugin } from "@opencode/core/plugin"
+import { Location } from "@opencode/core/location"
+import { LocationServiceMap } from "@opencode/core/location-services"
+import { ConflictError, InvalidRequestError, ServiceUnavailableError } from "@opencode/protocol/errors"
+import { VcsInitNotSupportedError } from "@opencode/protocol/groups/vcs"
 import { Effect } from "effect"
-import { HttpApiBuilder } from "effect/unstable/httpapi"
+import { HttpApiBuilder, HttpApiSchema } from "effect/unstable/httpapi"
 import { Api } from "../api"
 import { response } from "../location"
 
 export const VcsHandler = HttpApiBuilder.group(Api, "server.vcs", (handlers) =>
   Effect.gen(function* () {
+    const project = yield* Project.Service
+    const locations = yield* LocationServiceMap.Service
     return handlers
+      .handle("vcs.init", (ctx) =>
+        Effect.gen(function* () {
+          const location = yield* Location.Service
+          const directory = location.project.directory
+          const providerID = ctx.query.provider ?? "git"
+          yield* Plugin.awaitActivation
+          const vcs = yield* Vcs.Service
+          yield* vcs.initialize(providerID).pipe(
+            Effect.mapError((error) => {
+              if (error.kind === "missing")
+                return new InvalidRequestError({ message: "Project directory does not exist", field: "location" })
+              if (error.kind === "conflict")
+                return new ConflictError({ message: "Project already has version control", resource: directory })
+              if (error.kind === "unknown")
+                return new InvalidRequestError({
+                  message: "Unknown VCS provider",
+                  field: "provider",
+                })
+              if (error.kind === "unsupported")
+                return new VcsInitNotSupportedError({
+                  providerID,
+                  message: "VCS provider does not support initialization",
+                })
+              return new ServiceUnavailableError({ service: providerID, message: "VCS initialization failed" })
+            }),
+          )
+          if (!(yield* project.resolve(directory)).vcs)
+            return yield* new ServiceUnavailableError({ service: providerID, message: "VCS initialization failed" })
+          yield* locations.invalidate(
+            Location.Ref.make({ directory: location.directory, workspaceID: location.workspaceID }),
+          )
+          return HttpApiSchema.NoContent.make()
+        }),
+      )
       .handle("vcs.get", () =>
         response(
           Effect.gen(function* () {

packages/server/src/workerd.ts

@@ -96,6 +96,7 @@ const vcsLayer = Layer.succeed(
   Vcs.Service,
   Vcs.Service.of({
     base: () => Effect.succeed(null),
+    initialize: () => Effect.fail(new Vcs.InitializeError({ kind: "unsupported" })),
     transform: () => Effect.succeed({ dispose: Effect.void }),
     reload: () => Effect.void,
     info: () => Effect.succeed({ branch: {} }),

packages/server/test/vcs.test.ts

@@ -1,6 +1,6 @@
 import path from "node:path"
 import { $ } from "bun"
-import { expect } from "bun:test"
+import { describe, expect } from "bun:test"
 import { SdkPlugins } from "@opencode/core/plugin/sdk"
 import { Effect, Layer, Schedule } from "effect"
 import { tmpdir } from "../../core/test/fixture/tmpdir"
@@ -8,6 +8,204 @@ import { it } from "../../core/test/lib/effect"
 import { startServer } from "./fixture/server"
 import { ServerFetch } from "../src/fetch"
 
+it.live(
+  "initializes Git in a markerless project and refreshes its location",
+  () =>
+    Effect.gen(function* () {
+      const tmp = yield* Effect.acquireDisposable(Effect.promise(() => tmpdir("opencode-vcs-init-")))
+      yield* Effect.promise(() => Bun.write(path.join(tmp.path, "hello.txt"), "hello\n"))
+      const server = yield* startServer(path.join(tmp.path, "config"))
+      const url = new URL("/api/vcs/init", server.base)
+      url.searchParams.set("location[directory]", tmp.path)
+      const before = yield* Effect.promise(() =>
+        fetch(new URL(`/api/location${url.search}`, server.base), { headers: server.headers }),
+      )
+      expect(before.status).toBe(200)
+      const original = yield* Effect.promise(() => before.json())
+      const initialized = yield* Effect.promise(() => fetch(url, { method: "POST", headers: server.headers }))
+      expect(initialized.status).toBe(204)
+      expect(yield* Effect.promise(() => $`git -C ${tmp.path} rev-parse --is-inside-work-tree`.text())).toBe("true\n")
+      url.pathname = "/api/location"
+      const location = yield* Effect.promise(() => fetch(url, { headers: server.headers }))
+      expect(location.status).toBe(200)
+      const refreshed = yield* Effect.promise(() => location.json())
+      expect(refreshed).toMatchObject({ project: { directory: tmp.path } })
+      expect(refreshed.project.id).not.toBe(original.project.id)
+      const projects = yield* Effect.promise(() =>
+        fetch(new URL("/api/project", server.base), { headers: server.headers }),
+      )
+      expect(yield* Effect.promise(() => projects.json())).toContainEqual(
+        expect.objectContaining({ id: refreshed.project.id, vcs: "git" }),
+      )
+      url.pathname = "/api/vcs"
+      const vcs = yield* Effect.tryPromise({
+        try: async () => {
+          const response = await fetch(url, { headers: server.headers })
+          const body: unknown = await response.json()
+          if (!isRecord(body) || !isRecord(body.data) || body.data.provider !== "git")
+            throw new Error("Git provider not ready")
+          return body
+        },
+        catch: (cause) => cause,
+      }).pipe(Effect.retry(Schedule.spaced("10 millis")), Effect.timeout("2 seconds"))
+      expect(vcs).toMatchObject({ data: { provider: "git" } })
+      url.pathname = "/api/vcs/diff"
+      url.searchParams.set("mode", "working")
+      const diff = yield* Effect.promise(() => fetch(url, { headers: server.headers }))
+      expect(diff.status).toBe(200)
+      expect(yield* Effect.promise(() => diff.json())).toMatchObject({
+        data: expect.arrayContaining([expect.objectContaining({ file: "hello.txt" })]),
+      })
+      url.searchParams.delete("mode")
+      url.pathname = "/api/vcs/init"
+      const repeated = yield* Effect.promise(() => fetch(url, { method: "POST", headers: server.headers }))
+      expect(repeated.status).toBe(409)
+    }),
+  15_000,
+)
+
+it.live(
+  "does not create a project directory while initializing Git",
+  () =>
+    Effect.gen(function* () {
+      const tmp = yield* Effect.acquireDisposable(Effect.promise(() => tmpdir("opencode-vcs-missing-")))
+      const server = yield* startServer(path.join(tmp.path, "config"))
+      const directory = path.join(tmp.path, "absent")
+      const url = new URL("/api/vcs/init", server.base)
+      url.searchParams.set("location[directory]", directory)
+      const response = yield* Effect.promise(() => fetch(url, { method: "POST", headers: server.headers }))
+      expect(response.status).not.toBe(204)
+      expect(yield* Effect.promise(() => Bun.file(path.join(directory, ".git", "HEAD")).exists())).toBe(false)
+    }),
+  15_000,
+)
+
+it.live(
+  "accepts an explicit Git provider and rejects unknown providers without initializing",
+  () =>
+    Effect.gen(function* () {
+      const tmp = yield* Effect.acquireDisposable(Effect.promise(() => tmpdir("opencode-vcs-provider-")))
+      const server = yield* startServer(path.join(tmp.path, "config"))
+      const url = new URL("/api/vcs/init", server.base)
+      url.searchParams.set("location[directory]", tmp.path)
+      url.searchParams.set("provider", "unknown")
+      const unsupported = yield* Effect.promise(() => fetch(url, { method: "POST", headers: server.headers }))
+      expect(unsupported.status).toBe(400)
+      expect(yield* Effect.promise(() => unsupported.json())).toMatchObject({
+        _tag: "InvalidRequestError",
+        field: "provider",
+      })
+      expect(yield* Effect.promise(() => Bun.file(path.join(tmp.path, ".git", "HEAD")).exists())).toBe(false)
+      expect(yield* Effect.promise(() => Bun.file(path.join(tmp.path, ".hg", "requires")).exists())).toBe(false)
+      url.searchParams.set("provider", "git")
+      const initialized = yield* Effect.promise(() => fetch(url, { method: "POST", headers: server.headers }))
+      expect(initialized.status).toBe(204)
+      expect(yield* Effect.promise(() => Bun.file(path.join(tmp.path, ".git", "HEAD")).exists())).toBe(true)
+    }),
+  15_000,
+)
+
+it.live("returns 501 when a registered VCS provider has no initializer", () =>
+  Effect.gen(function* () {
+    const tmp = yield* Effect.acquireDisposable(Effect.promise(() => tmpdir("opencode-vcs-no-init-")))
+    const handler = yield* ServerFetch.make(
+      {
+        database: { path: ":memory:" },
+        config: { directory: tmp.path },
+        fs: { filewatcher: false },
+        models: { fetch: false },
+      },
+      {
+        overrides: [
+          SdkPlugins.node.replace(
+            Layer.succeed(
+              SdkPlugins.Service,
+              SdkPlugins.Service.of({
+                register: () => Effect.void,
+                all: () => [
+                  {
+                    id: "read-only-vcs",
+                    revision: "test",
+                    effect: (ctx) =>
+                      ctx.vcs
+                        .transform((editor) => {
+                          editor.add({
+                            id: "read-only",
+                            name: "Read-only VCS",
+                            info: () => Effect.succeed({ branch: {} }),
+                            branches: () => Effect.succeed([]),
+                            status: () => Effect.succeed([]),
+                            diff: () => Effect.succeed([]),
+                          })
+                        })
+                        .pipe(Effect.asVoid),
+                  },
+                ],
+              }),
+            ),
+          ),
+        ],
+      },
+    )
+    const url = new URL("http://opencode.local/api/vcs/init")
+    url.searchParams.set("location[directory]", tmp.path)
+    url.searchParams.set("provider", "read-only")
+    const response = yield* Effect.promise(() => handler(new Request(url, { method: "POST" })))
+    expect(response.status).toBe(501)
+    expect(yield* Effect.promise(() => response.json())).toMatchObject({
+      _tag: "VcsInitNotSupportedError",
+      providerID: "read-only",
+    })
+    expect(yield* Effect.promise(() => Bun.file(path.join(tmp.path, ".git", "HEAD")).exists())).toBe(false)
+    expect(yield* Effect.promise(() => Bun.file(path.join(tmp.path, ".hg", "requires")).exists())).toBe(false)
+  }),
+)
+
+const describeHg = Bun.which("hg") ? describe : describe.skip
+
+describeHg("Mercurial initialization", () => {
+  it.live(
+    "initializes and serves an untracked-file diff through the Hg provider",
+    () =>
+      Effect.gen(function* () {
+        const tmp = yield* Effect.acquireDisposable(Effect.promise(() => tmpdir("opencode-vcs-hg-init-")))
+        yield* Effect.promise(() => Bun.write(path.join(tmp.path, "hello.txt"), "hello\n"))
+        const server = yield* startServer(path.join(tmp.path, "config"))
+        const url = new URL("/api/vcs/init", server.base)
+        url.searchParams.set("location[directory]", tmp.path)
+        url.searchParams.set("provider", "hg")
+        const initialized = yield* Effect.promise(() => fetch(url, { method: "POST", headers: server.headers }))
+        expect(initialized.status).toBe(204)
+        expect(yield* Effect.promise(() => Bun.file(path.join(tmp.path, ".hg", "requires")).exists())).toBe(true)
+        url.pathname = "/api/vcs"
+        const info = yield* Effect.tryPromise({
+          try: async () => {
+            const response = await fetch(url, { headers: server.headers })
+            const body: unknown = await response.json()
+            if (!isRecord(body) || !isRecord(body.data) || body.data.provider !== "hg")
+              throw new Error("Mercurial provider not ready")
+            return body
+          },
+          catch: (cause) => cause,
+        }).pipe(Effect.retry(Schedule.spaced("10 millis")), Effect.timeout("2 seconds"))
+        expect(info).toMatchObject({ data: { provider: "hg" } })
+        url.pathname = "/api/vcs/diff"
+        url.searchParams.set("mode", "working")
+        const diff = yield* Effect.promise(() => fetch(url, { headers: server.headers }))
+        expect(diff.status).toBe(200)
+        expect(yield* Effect.promise(() => diff.json())).toMatchObject({
+          data: expect.arrayContaining([expect.objectContaining({ file: "hello.txt" })]),
+        })
+        url.pathname = "/api/vcs/init"
+        url.searchParams.delete("mode")
+        url.searchParams.set("provider", "git")
+        const repeated = yield* Effect.promise(() => fetch(url, { method: "POST", headers: server.headers }))
+        expect(repeated.status).toBe(409)
+      }),
+    15_000,
+  )
+})
+
 it.live(
   "serves lazy review bases, committed diffs, and unavailable-base errors",
   () =>

services/www/src/docs/content/build/plugins/effect.mdx

@@ -1061,6 +1061,11 @@ Provider callbacks receive the current location, working-copy root, canonical pr
 store. Diff callbacks also receive the selected mode, requested context, and output byte budget. Repository discovery
 continues to use OpenCode's built-in Git and Mercurial detectors.
 
+Providers can optionally implement `init(scope)` to create a repository in `scope.worktree`. Initialization selects
+the provider by ID (Git by default), not by the detected repository type. Register a provider with `init` even when
+the location has no repository yet; OpenCode checks that the directory exists and has no repository before calling
+it, then rediscovers the project. New repository formats still need discovery support beyond this callback.
+
 Schemas: [`Vcs.Info`](/api#schema-Vcs.Info), [`Vcs.FileStatus`](/api#schema-Vcs.FileStatus),
 [`FileDiff.Info`](/api#schema-FileDiff.Info).
 
@@ -1073,10 +1078,15 @@ interface VcsEditor {
   }
 }
 
-interface VcsDomain extends VcsApi<unknown> {
+interface VcsDomain extends Omit<VcsApi<unknown>, "init"> {
   readonly transform: Transform<VcsEditor>
   readonly reload: () => Effect.Effect<void>
 }
+
+interface VcsDefinition {
+  readonly init?: (scope: VcsScope) => Effect.Effect<void, unknown>
+  // Existing info, branches, status, and diff callbacks are required.
+}
 ```
 
 ### Websearch

services/www/src/docs/content/build/plugins/index.mdx

@@ -1029,6 +1029,11 @@ Provider callbacks receive the current location, working-copy root, canonical pr
 store. Diff callbacks also receive the selected mode, requested context, and output byte budget. Repository discovery
 continues to use OpenCode's built-in Git and Mercurial detectors.
 
+Providers can optionally implement `init(scope, { signal })` to create a repository in `scope.worktree`. Initialization
+selects the provider by ID (Git by default), not by the detected repository type. Register a provider with `init` even
+when the location has no repository yet; OpenCode checks that the directory exists and has no repository before calling
+it, then rediscovers the project. New repository formats still need discovery support beyond this callback.
+
 #### Reference
 
 Schemas: [`Vcs.Info`](/api#schema-Vcs.Info), [`Vcs.FileStatus`](/api#schema-Vcs.FileStatus),
@@ -1051,6 +1056,11 @@ interface VcsEditor {
     set(providerID: string): void
   }
 }
+
+interface VcsDefinition {
+  init?(scope: VcsScope, context: { signal: AbortSignal }): Promise<void>
+  // Existing info, branches, status, and diff callbacks are required.
+}
 ```
 
 ### Worktrees