@john-ezra/openralph 0.1.1

package/src/git.ts

@@ -0,0 +1,62 @@
+import { runCommand, type CommandResult } from "./exec.ts"
+
+const DEFENSIVE_GIT_CONFIG = [
+  ["core.hooksPath", "/dev/null"],
+  ["core.fsmonitor", "false"],
+  ["core.pager", "cat"],
+] as const
+
+export interface GitContext {
+  root: string
+  branch: string
+}
+
+export async function requireGitContext(cwd: string): Promise<GitContext> {
+  const root = await runGit(["rev-parse", "--show-toplevel"], cwd)
+  const branchResult = await runGitCommand(["branch", "--show-current"], root.stdout.trim())
+  const branch = branchResult.exitCode === 0 && branchResult.stdout.trim() ? branchResult.stdout.trim() : "HEAD"
+  return { root: root.stdout.trim(), branch }
+}
+
+export function buildDefensiveGitArgs(args: string[]): string[] {
+  return ["--no-pager", ...DEFENSIVE_GIT_CONFIG.flatMap(([key, value]) => ["-c", `${key}=${value}`]), ...args]
+}
+
+export function runGitCommand(args: string[], cwd: string): Promise<CommandResult> {
+  return runCommand("git", buildDefensiveGitArgs(args), cwd)
+}
+
+export async function getHead(cwd: string): Promise<string | undefined> {
+  const result = await runGitCommand(["rev-parse", "HEAD"], cwd)
+  if (result.exitCode !== 0) return undefined
+  return result.stdout.trim()
+}
+
+export async function isWorktreeClean(cwd: string): Promise<boolean> {
+  const result = await runGit(["status", "--porcelain"], cwd)
+  return result.stdout.trim() === ""
+}
+
+export async function tagExists(cwd: string, tagName: string): Promise<boolean> {
+  const result = await runGitCommand(["rev-parse", "-q", "--verify", `refs/tags/${tagName}`], cwd)
+  return result.exitCode === 0
+}
+
+export async function createLightweightTag(cwd: string, tagName: string): Promise<void> {
+  if (await tagExists(cwd, tagName)) throw new Error(`tag already exists: ${tagName}`)
+  await runGit(["tag", tagName], cwd)
+}
+
+export async function pushCurrentBranch(cwd: string, branch: string): Promise<void> {
+  if (!branch || branch === "HEAD") throw new Error("cannot push from detached HEAD")
+  await runGit(["push", "origin", branch], cwd)
+}
+
+async function runGit(args: string[], cwd: string) {
+  const result = await runGitCommand(args, cwd)
+  if (result.exitCode !== 0) {
+    const detail = (result.stderr || result.stdout).trim()
+    throw new Error(detail || `git ${args.join(" ")} failed`)
+  }
+  return result
+}

package/src/launcher.ts

@@ -0,0 +1,235 @@
+import { formatLoopArgsForReplay, parseLoopArgs, resolveDockerOptions, validateOptions, type LoopPhase, type OpenRalphOptions, type ParsedLoopArgs } from "./args.ts"
+import { CONTAINER_WORKSPACE, runDockerLoop } from "./docker.ts"
+import { commandExists as defaultCommandExists, type CommandOutputEvent, type CommandResult } from "./exec.ts"
+import { requireGitContext } from "./git.ts"
+import { formatSummary, runLoop, type LoopSummary } from "./loop.ts"
+import { attestDockerEnvironment, hasDockerMarker, type TrustDeps } from "./trust.ts"
+
+export type LauncherMode = "docker-host-launch" | "host-explicit" | "host-config-default" | "container-attested"
+
+export interface RunLauncherInput {
+  phase: LoopPhase
+  rawArgs: string
+  cwd: string
+  options: OpenRalphOptions
+  streamOutput?: boolean
+  captureOutput?: boolean
+  onOutput?: (event: CommandOutputEvent) => void
+  signal?: AbortSignal
+}
+
+export interface LauncherResult {
+  phase: LoopPhase
+  mode: LauncherMode
+  status: LoopSummary["status"]
+  summary: string
+  outputTail?: string
+}
+
+export interface RunLauncherDeps {
+  env?: NodeJS.ProcessEnv
+  requireGitContext?: typeof requireGitContext
+  runDockerLoop?: typeof runDockerLoop
+  runLoop?: typeof runLoop
+  commandExists?: typeof defaultCommandExists
+  trust?: TrustDeps
+}
+
+export interface ResolveLauncherModeInput {
+  parsed: ParsedLoopArgs
+  options: OpenRalphOptions
+  env?: NodeJS.ProcessEnv
+  trust?: TrustDeps
+}
+
+export async function runOpenRalphLauncher(input: RunLauncherInput, deps: RunLauncherDeps = {}): Promise<LauncherResult> {
+  const parsed = parseLoopArgs(input.phase, input.rawArgs)
+  const mode = await resolveLauncherMode({ parsed, options: input.options, env: deps.env, trust: deps.trust })
+
+  if (mode === "docker-host-launch") {
+    if (input.phase === "build" && parsed.push) {
+      throw new Error("OpenRalph Build --push is not supported in Docker mode. Run without --push, review the local commits, then push from the host.")
+    }
+  }
+
+  await preflightCommands(mode, deps.commandExists ?? defaultCommandExists)
+
+  if (mode === "docker-host-launch") {
+    const git = await (deps.requireGitContext ?? requireGitContext)(input.cwd)
+    const result = await (deps.runDockerLoop ?? runDockerLoop)({
+      phase: input.phase,
+      rawArgs: input.rawArgs,
+      projectRoot: git.root,
+      options: input.options,
+      streamOutput: input.streamOutput,
+      captureOutput: input.captureOutput,
+      onOutput: input.onOutput,
+      signal: input.signal,
+    })
+
+    if (result.exitCode !== 0) {
+      throw new Error(formatDockerFailure(input.phase, parsed, result))
+    }
+
+    const output = commandOutput(result)
+    const displayOutput = translateContainerPaths(output, git.root) ?? ""
+    const innerSummary = translateContainerPaths(extractOpenRalphSummary(input.phase, output), git.root)
+    if (innerSummary?.startsWith(`OpenRalph ${input.phase} failed:`)) {
+      throw new Error(formatDockerInnerFailure(input.phase, innerSummary))
+    }
+
+    return {
+      phase: input.phase,
+      mode,
+      status: "complete",
+      summary: formatDockerSuccess(input.phase, result, git.root),
+      outputTail: displayOutput ? tailLines(displayOutput, 80) : undefined,
+    }
+  }
+
+  const loopSummary = await (deps.runLoop ?? runLoop)({
+    phase: input.phase,
+    rawArgs: input.rawArgs,
+    cwd: input.cwd,
+    options: input.options,
+    executionMode: mode,
+    streamOutput: input.streamOutput,
+    onOutput: input.onOutput,
+    signal: input.signal,
+  })
+
+  return {
+    phase: input.phase,
+    mode,
+    status: loopSummary.status,
+    summary: formatSummary(loopSummary),
+  }
+}
+
+export async function resolveLauncherMode(input: ResolveLauncherModeInput): Promise<LauncherMode> {
+  const env = input.env ?? process.env
+  const docker = resolveDockerOptions(input.options)
+
+  if (await hasDockerMarker(env, input.trust)) {
+    if (!(await attestDockerEnvironment(env, input.trust))) {
+      throw new Error("OpenRalph Docker attestation failed. Refusing to run a loop with untrusted Docker markers or token state.")
+    }
+    return "container-attested"
+  }
+
+  if (docker.enabled && !input.parsed.noDocker) return "docker-host-launch"
+  if (input.parsed.noDocker) return "host-explicit"
+  return "host-config-default"
+}
+
+export function readOptionsFromEnv(env: NodeJS.ProcessEnv = process.env): OpenRalphOptions {
+  const raw = env.OPENRALPH_OPTIONS_JSON
+  if (!raw) return {}
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`OPENRALPH_OPTIONS_JSON must be valid JSON: ${formatError(error)}`)
+  }
+
+  return validateOptions(parsed)
+}
+
+export function formatDockerSuccess(phase: LoopPhase, result: CommandResult, projectRoot?: string): string {
+  const output = translateContainerPaths(commandOutput(result), projectRoot) ?? ""
+  const summary = extractOpenRalphSummary(phase, output)
+  const lines = [`OpenRalph ${phase} Docker execution completed.`]
+
+  if (summary) {
+    lines.push("", summary)
+  } else if (output) {
+    lines.push("", "Container output tail:", tailLines(output, 80))
+  }
+
+  return lines.join("\n")
+}
+
+export function formatDockerInnerFailure(phase: LoopPhase, summary: string): string {
+  return [
+    `OpenRalph Docker execution finished, but the ${phase} loop reported failure.`,
+    "",
+    summary,
+    "",
+    "Review the worktree before rerunning; the failed child may have left partial changes.",
+  ].join("\n")
+}
+
+export function formatDockerFailure(phase: LoopPhase, parsed: ParsedLoopArgs, result: CommandResult): string {
+  const reason = result.exitCode === null ? `signal ${result.signal ?? "unknown"}` : `exit code ${result.exitCode}`
+  const output = commandOutput(result)
+  const lines = [
+    `OpenRalph Docker execution failed: Docker exited with ${reason}`,
+    "",
+    "OpenRalph did not fall back to host execution because Docker mode is enabled.",
+    "Fix the Docker issue and rerun the command.",
+    "",
+    "If you intentionally want to run this loop on the host, rerun with:",
+    `  ${noDockerCommand(phase, parsed)}`,
+  ]
+
+  if (output) lines.push("", "Container output tail:", tailLines(output, 80))
+  return lines.join("\n")
+}
+
+async function preflightCommands(mode: LauncherMode, exists: typeof defaultCommandExists): Promise<void> {
+  const required = mode === "docker-host-launch" ? ["git", "docker"] : ["git", "opencode"]
+  const missing: string[] = []
+
+  for (const command of required) {
+    if (!(await exists(command))) missing.push(command)
+  }
+
+  if (missing.length > 0) throw new Error(formatMissingCommands(missing))
+}
+
+function formatMissingCommands(commands: string[]): string {
+  const hints: Record<string, string> = {
+    git: "Install git and ensure it is on PATH.",
+    opencode: "Install opencode (https://opencode.ai) and ensure it is on PATH.",
+    docker: "Install Docker and ensure the docker executable is on PATH.",
+  }
+
+  return [
+    `OpenRalph required command${commands.length === 1 ? "" : "s"} not found on PATH: ${commands.join(", ")}.`,
+    ...commands.map((command) => `${command}: ${hints[command] ?? "Install it and ensure it is on PATH."}`),
+  ].join("\n")
+}
+
+function noDockerCommand(phase: LoopPhase, parsed: ParsedLoopArgs): string {
+  const replayArgs = formatLoopArgsForReplay(parsed)
+  return `/ralph-${phase}${replayArgs ? ` ${replayArgs}` : ""} --no-docker`
+}
+
+function commandOutput(result: CommandResult): string {
+  return `${result.stdout}\n${result.stderr}`.trim()
+}
+
+function translateContainerPaths(value: string | undefined, projectRoot: string | undefined): string | undefined {
+  if (!value || !projectRoot) return value
+  return value.split(`${CONTAINER_WORKSPACE}/runs/`).join(`${projectRoot}/runs/`)
+}
+
+function extractOpenRalphSummary(phase: LoopPhase, output: string): string | undefined {
+  const lines = output.split(/\r?\n/)
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    if (lines[index].startsWith(`OpenRalph ${phase} `)) {
+      return lines.slice(index, Math.min(lines.length, index + 8)).join("\n").trim()
+    }
+  }
+  return undefined
+}
+
+function tailLines(input: string, maxLines: number): string {
+  const lines = input.split(/\r?\n/)
+  return lines.slice(Math.max(0, lines.length - maxLines)).join("\n")
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/loop.ts

@@ -0,0 +1,339 @@
+import { parseLoopArgs, resolveModel, type LoopPhase, type OpenRalphOptions } from "./args.ts"
+import { createRunArtifacts, finishRunArtifacts, startIterationArtifacts } from "./artifacts.ts"
+import { startCommand, type CommandOutputEvent, type CommandResult } from "./exec.ts"
+import { requireGitContext, getHead, isWorktreeClean, createLightweightTag, pushCurrentBranch } from "./git.ts"
+import { detectBuildSentinel, isPlanComplete } from "./sentinels.ts"
+import { createBuildTagName } from "./tags.ts"
+import { createHostLoopToken } from "./trust.ts"
+
+export type LoopExecutionMode = "host-explicit" | "host-config-default" | "container-attested"
+
+export interface RunLoopInput {
+  phase: LoopPhase
+  rawArgs: string
+  cwd: string
+  options: OpenRalphOptions
+  executionMode?: LoopExecutionMode
+  streamOutput?: boolean
+  onOutput?: (event: CommandOutputEvent) => void
+  signal?: AbortSignal
+}
+
+export interface LoopSummary {
+  phase: LoopPhase
+  status: "complete" | "max-reached" | "failed" | "stopped"
+  message: string
+  launched: number
+  tagged: number
+  blocked: number
+  warnings: string[]
+  artifacts: string
+}
+
+export async function runLoop(input: RunLoopInput): Promise<LoopSummary> {
+  const args = parseLoopArgs(input.phase, input.rawArgs)
+  const model = resolveModel(input.phase, args, input.options)
+  const git = await requireGitContext(input.cwd)
+  const streamOutput = input.streamOutput ?? true
+  const warnings: string[] = []
+  const artifacts = await createRunArtifacts({ projectRoot: git.root, phase: input.phase, rawArgs: input.rawArgs })
+
+  if (git.branch === "main" || git.branch === "master") {
+    const warning = `warning: running OpenRalph on ${git.branch}`
+    warnings.push(warning)
+    if (streamOutput) process.stderr.write(`OpenRalph ${warning}\n`)
+  }
+
+  const hostWarning = hostModeWarning(input.executionMode)
+  if (hostWarning) {
+    warnings.push(hostWarning)
+    if (streamOutput) process.stderr.write(`OpenRalph ${hostWarning}\n`)
+  }
+
+  const state = {
+    launched: 0,
+    tagged: 0,
+    blocked: 0,
+    consecutiveFailures: 0,
+    lastFailure: undefined as string | undefined,
+    stopRequested: false,
+    forceStopRequested: false,
+    activeChild: undefined as ReturnType<typeof startCommand>["child"] | undefined,
+  }
+
+  const requestStop = (force: boolean, announce: boolean) => {
+    if (!state.stopRequested) {
+      state.stopRequested = true
+      state.activeChild?.kill("SIGINT")
+      if (!force && announce) process.stderr.write("\nOpenRalph stop requested. Waiting for active child to exit...\n")
+      return
+    }
+
+    if (force) {
+      state.forceStopRequested = true
+      state.activeChild?.kill("SIGKILL")
+      if (announce) process.stderr.write("\nOpenRalph force stop requested. Terminating active child...\n")
+    }
+  }
+
+  const onSigint = () => {
+    requestStop(state.stopRequested, true)
+  }
+
+  const onAbort = () => requestStop(false, false)
+
+  const loopChild = await buildLoopChildEnv(input.executionMode)
+  process.on("SIGINT", onSigint)
+  if (input.signal?.aborted) onAbort()
+  else input.signal?.addEventListener("abort", onAbort, { once: true })
+  try {
+    const runId = input.phase === "build" ? artifacts.timestampId : undefined
+
+    const finish = async (status: LoopSummary["status"], message: string): Promise<LoopSummary> => {
+      const result = summary(input.phase, status, message, state, warnings, artifacts.dir)
+      await finishRunArtifacts(artifacts, result)
+      return result
+    }
+
+    const tagCleanBuildCommit = async (dirtyMessage: string): Promise<LoopSummary | undefined> => {
+      if (!(await isWorktreeClean(git.root))) {
+        return finish("failed", dirtyMessage)
+      }
+
+      const tagName = createBuildTagName(runId ?? artifacts.timestampId, state.tagged + 1)
+      let tagged = false
+      try {
+        await createLightweightTag(git.root, tagName)
+        state.tagged += 1
+        tagged = true
+      } catch (error) {
+        const warning = `warning: failed to tag build commit (${tagName}): ${formatError(error)}`
+        warnings.push(warning)
+        if (streamOutput) process.stderr.write(`OpenRalph ${warning}\n`)
+      }
+
+      if (args.push) {
+        try {
+          await pushCurrentBranch(git.root, git.branch)
+        } catch (error) {
+          const tagStatus = tagged ? " and is tagged locally" : ""
+          return finish(
+            "failed",
+            `build commit succeeded${tagStatus}, but pushing ${git.branch} failed: ${formatError(error)}. Push manually from the host.`,
+          )
+        }
+      }
+
+      return undefined
+    }
+
+    while (!state.stopRequested) {
+      if (args.maxIterations !== undefined && state.launched >= args.maxIterations) {
+        if (state.consecutiveFailures > 0) {
+          return finish("failed", `reached max iterations (${args.maxIterations}) after a failed child; last failure: ${state.lastFailure}`)
+        }
+        return finish("max-reached", `reached max iterations (${args.maxIterations})`)
+      }
+
+      const beforeHead = input.phase === "build" ? await getHead(git.root) : undefined
+      const childArgs = buildChildArgs(input.phase, git.root, model)
+      state.launched += 1
+      const iterationArtifacts = await startIterationArtifacts(artifacts, state.launched, childArgs)
+
+      let result: CommandResult
+      try {
+        const child = startCommand("opencode", childArgs, {
+          cwd: git.root,
+          env: loopChild.env,
+          streamOutput,
+          onOutput: (event) => {
+            iterationArtifacts.recordOutput(event)
+            input.onOutput?.(event)
+          },
+          signal: input.signal,
+        })
+        state.activeChild = child.child
+        result = await child.result
+      } catch (error) {
+        state.activeChild = undefined
+        await iterationArtifacts.finish({ error })
+        if (state.stopRequested || state.forceStopRequested || input.signal?.aborted) {
+          return finish("stopped", `stopped by user after ${state.launched} launched iteration(s)`)
+        }
+
+        const failed = recordFailure(input.phase, state, `child process failed to start: ${formatError(error)}`, streamOutput)
+        if (failed) return finish("failed", failed)
+        continue
+      }
+      state.activeChild = undefined
+
+      const output = `${result.stdout}\n${result.stderr}`
+
+      if (state.stopRequested || state.forceStopRequested || input.signal?.aborted) {
+        await iterationArtifacts.finish({ result, status: "stopped by user" })
+        return finish("stopped", `stopped by user after ${state.launched} launched iteration(s)`)
+      }
+
+      if (result.exitCode !== 0) {
+        await iterationArtifacts.finish({ result, status: "child process failed" })
+        const failed = recordFailure(input.phase, state, `child process failed with exit code ${result.exitCode ?? `signal ${result.signal}`}`, streamOutput)
+        if (failed) return finish("failed", failed)
+        continue
+      }
+
+      if (input.phase === "plan") {
+        const planComplete = isPlanComplete(output)
+        await iterationArtifacts.finish({ result, status: planComplete ? "planning complete" : "planning continues", sentinel: planComplete ? "RALPH_PLAN_COMPLETE" : undefined })
+        state.consecutiveFailures = 0
+        state.lastFailure = undefined
+        if (planComplete) {
+          return finish("complete", "planning complete")
+        }
+        continue
+      }
+
+      const sentinel = detectBuildSentinel(output)
+      await iterationArtifacts.finish({ result, status: `build sentinel: ${sentinel}`, sentinel: sentinel === "none" ? undefined : sentinel })
+      if (sentinel === "complete") {
+        const afterHead = await getHead(git.root)
+        if (afterHead && afterHead !== beforeHead) {
+          const failed = await tagCleanBuildCommit("build completion reported with a dirty worktree; not tagging")
+          if (failed) return failed
+        } else if (!(await isWorktreeClean(git.root))) {
+          return finish("failed", "build completion reported with a dirty worktree; completed work must be committed before finishing")
+        }
+
+        state.consecutiveFailures = 0
+        state.lastFailure = undefined
+        return finish("complete", "build complete")
+      }
+
+      if (sentinel === "blocked") {
+        state.consecutiveFailures = 0
+        state.lastFailure = undefined
+        state.blocked += 1
+        continue
+      }
+
+      if (sentinel === "none") {
+        const failed = recordFailure(input.phase, state, "build child exited successfully without a Ralph sentinel", streamOutput)
+        if (failed) return finish("failed", failed)
+        continue
+      }
+
+      const afterHead = await getHead(git.root)
+      if (!afterHead || afterHead === beforeHead) {
+        const failed = recordFailure(input.phase, state, "build iteration reported completion but did not create a new commit", streamOutput)
+        if (failed) return finish("failed", failed)
+        continue
+      }
+
+      const failed = await tagCleanBuildCommit("build iteration completed with a dirty worktree; not tagging")
+      if (failed) return failed
+
+      state.consecutiveFailures = 0
+      state.lastFailure = undefined
+    }
+
+    return finish("stopped", `stopped by user after ${state.launched} launched iteration(s)`)
+  } finally {
+    process.off("SIGINT", onSigint)
+    input.signal?.removeEventListener("abort", onAbort)
+    await loopChild.cleanup()
+  }
+}
+
+async function buildLoopChildEnv(executionMode: LoopExecutionMode | undefined): Promise<{
+  env: Record<string, string>
+  cleanup: () => Promise<void>
+}> {
+  if (executionMode === "container-attested") {
+    return { env: { OPENRALPH_LOOP_CHILD: "1" }, cleanup: async () => {} }
+  }
+
+  const hostToken = await createHostLoopToken()
+  return {
+    env: {
+      OPENRALPH_LOOP_CHILD: "1",
+      ...hostToken.env,
+    },
+    cleanup: hostToken.cleanup,
+  }
+}
+
+function buildChildArgs(phase: LoopPhase, projectRoot: string, model: string | undefined): string[] {
+  const args = [
+    "run",
+    "--dir",
+    projectRoot,
+    "--command",
+    phase === "plan" ? "ralph-plan-iteration" : "ralph-build-iteration",
+    "--dangerously-skip-permissions",
+  ]
+
+  if (model) args.push("--model", model)
+  return args
+}
+
+function hostModeWarning(mode: LoopExecutionMode | undefined): string | undefined {
+  if (mode === "container-attested") return undefined
+  if (mode === "host-explicit") {
+    return "warning: --no-docker selected; child iterations run on the host with --dangerously-skip-permissions"
+  }
+  return "warning: host mode runs child iterations on this machine with --dangerously-skip-permissions"
+}
+
+function recordFailure(
+  phase: LoopPhase,
+  state: { consecutiveFailures: number; lastFailure?: string },
+  reason: string,
+  streamOutput: boolean,
+): string | undefined {
+  state.consecutiveFailures += 1
+  state.lastFailure = reason
+  if (streamOutput) process.stderr.write(`\nOpenRalph ${phase} iteration failed: ${reason}\n`)
+  if (state.consecutiveFailures >= 3) {
+    return `stopped after 3 consecutive child failures; last failure: ${reason}`
+  }
+  return undefined
+}
+
+function summary(
+  phase: LoopPhase,
+  status: LoopSummary["status"],
+  message: string,
+  state: { launched: number; tagged: number; blocked: number },
+  warnings: string[],
+  artifacts: string,
+): LoopSummary {
+  return {
+    phase,
+    status,
+    message,
+    launched: state.launched,
+    tagged: state.tagged,
+    blocked: state.blocked,
+    warnings,
+    artifacts,
+  }
+}
+
+export function formatSummary(summary: LoopSummary): string {
+  const lines = [
+    `OpenRalph ${summary.phase} ${summary.status}: ${summary.message}`,
+    `launched iterations: ${summary.launched}`,
+    `artifacts: ${summary.artifacts}`,
+  ]
+
+  if (summary.phase === "build") {
+    lines.push(`tagged iterations: ${summary.tagged}`)
+    lines.push(`blocked iterations: ${summary.blocked}`)
+  }
+
+  for (const warning of summary.warnings) lines.push(warning)
+  return lines.join("\n")
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/plugin.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import type { Plugin } from "@opencode-ai/plugin"
+import { validateOptions, type OpenRalphOptions } from "./args.ts"
+import { authorizeLoopChild } from "./trust.ts"
+
+const pluginDir = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(pluginDir, "..")
+const ORCHESTRATOR_AGENT = "openralph-orchestrator"
+
+export default (async ({ directory }, rawOptions) => {
+  validateOptions(rawOptions)
+
+  return {
+    config: async (cfg) => {
+      cfg.command ??= {}
+      delete cfg.command["ralph-define"]
+      delete cfg.command["ralph-plan"]
+      delete cfg.command["ralph-build"]
+      if (cfg.agent) delete cfg.agent[ORCHESTRATOR_AGENT]
+
+      if (await authorizeLoopChild(process.env, directory)) {
+        cfg.command["ralph-plan-iteration"] = {
+          description: "Run one Ralph planning iteration",
+          template: readPrompt("PROMPT_plan.md"),
+        }
+        cfg.command["ralph-build-iteration"] = {
+          description: "Run one Ralph build iteration",
+          template: readPrompt("PROMPT_build.md"),
+        }
+      }
+    },
+    "command.execute.before": async (input, output) => {
+      if (input.command !== "ralph-define" && input.command !== "ralph-plan" && input.command !== "ralph-build") return
+      output.parts = []
+      throw new Error(
+        `/${input.command} has been replaced by the OpenRalph TUI menu. Remove any stale prompt-backed ${input.command} command file/config, load the OpenRalph TUI plugin, and run /ralph instead.`,
+      )
+    },
+  }
+}) satisfies Plugin
+
+function readPrompt(fileName: string): string {
+  try {
+    return readFileSync(resolve(packageRoot, fileName), "utf8")
+  } catch (error) {
+    throw new Error(`OpenRalph could not read bundled prompt ${fileName}; the package may be installed incompletely: ${formatError(error)}`)
+  }
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export type { OpenRalphOptions }