@oisincoveney/pipeline 2.8.4 → 2.9.0

package/dist/cli/program.d.ts

@@ -1,35 +1,33 @@
 import { runPipelineFromConfig } from "../pipeline-runtime.js";
+import { RunEffort, RunMode, RunTarget } from "../run-control/contracts.js";
+import { Effect } from "effect";
 import { Command } from "commander";
 
 //#region src/cli/program.d.ts
 interface ExecuteOptions {
   entrypoint?: string;
   pipelineRunner?: typeof runPipelineFromConfig;
+  runControl?: RunControlOptions;
+  runId?: string;
+  runStoreMode?: RunStoreMode;
   schedule?: string;
+  supervised?: boolean;
+  supervisor?: boolean;
   workflow?: string;
 }
+type RunStoreMode = "create" | "reuse";
+interface RunControlOptions {
+  effort?: RunEffort;
+  mode?: RunMode;
+  target?: RunTarget;
+}
 /**
  * Config-driven `execute` entrypoint. Package-owned defaults are the source of
  * truth; repo-local pipeline files are ignored by runtime loading.
  */
 declare function execute(description: string, options?: ExecuteOptions): Promise<void>;
 declare function quick(description: string, options?: Omit<ExecuteOptions, "entrypoint">): Promise<void>;
-interface DoctorCheck {
-  detail: string;
-  name: string;
-  passed: boolean;
-}
-interface DoctorResult {
-  checks: DoctorCheck[];
-  passed: boolean;
-}
-interface DoctorFlags {
-  cluster?: boolean | string;
-  kubeContext?: string;
-  kubeconfig?: string;
-}
 declare function createCliProgram(): Command;
 declare function runCli(argv: string[]): Promise<void>;
-declare function runDoctor(cwd: string, options?: DoctorFlags): Promise<DoctorResult>;
 //#endregion
-export { createCliProgram, execute, quick, runCli, runDoctor };
+export { createCliProgram, execute, quick, runCli };

package/dist/cli/program.js

@@ -1,28 +1,32 @@
-import { PipelineConfigError } from "../config/schemas.js";
 import { loadPipelineConfig } from "../config/load.js";
 import "../config.js";
+import { configureGatewayHosts, localGatewayStatus, reconcileGateway, renderGatewayConfig, runGatewayDoctor, startLocalGateway } from "../mcp/gateway.js";
 import { createOrchestratorLaunchPlan, createRunnerLaunchPlan } from "../runner.js";
 import { compileWorkflowPlan } from "../planning/compile.js";
+import { generateRuntimeRunId } from "../runtime/context/context.js";
+import "../runtime/context/index.js";
+import { runPipelineFromConfig } from "../pipeline-runtime.js";
 import { compileScheduleArtifact, generateScheduleArtifact, parseScheduleArtifact } from "../planning/generate.js";
-import { loadMokaGlobalConfig } from "../moka-global-config.js";
-import { defaultClusterDoctorNamespace, runClusterDoctor } from "../cluster-doctor.js";
 import { formatCodexAuthSyncResult, syncLocalCodexAuth } from "../codex-auth-sync.js";
 import { registerBenchCommand } from "../commands/bench-command.js";
 import { registerConfiguredEntrypointCommands } from "../commands/pipeline-command.js";
-import { configureGatewayHosts, localGatewayStatus, reconcileGateway, renderGatewayConfig, runGatewayDoctor, startLocalGateway } from "../mcp/gateway.js";
-import { generateRuntimeRunId } from "../runtime/context/context.js";
-import "../runtime/context/index.js";
-import { runPipelineFromConfig } from "../pipeline-runtime.js";
 import { registerRunnerCommandCommand } from "../commands/runner-command-command.js";
 import { formatConfigLintWarning, lintPipelineConfig } from "../config/lint.js";
 import { formatInstallCommandsResult, installCommands, parseCommandHost } from "../install-commands.js";
 import { formatPipelineInitResult, initPipelineProject } from "../pipeline-init.js";
+import { createRun, runControlStatusPaths, updateRunController } from "../run-control/store.js";
+import { registerRunControlCommands } from "../run-control/commands.js";
+import { startDetachedRunController } from "../run-control/detach.js";
+import { createRunStoreRuntimeReporter } from "../run-control/runtime-reporter.js";
+import { createRunControlSupervisor } from "../run-control/supervisor.js";
+import { runDoctor } from "./doctor.js";
 import { createTerminalRuntimeReporter, formatDoctorResult, formatRuntimeFailure, formatRuntimeResult } from "./format.js";
+import { MOKA_RUN_EFFORTS, MOKA_RUN_TARGETS, resolveMokaRun } from "./run-resolver.js";
 import { addMokaSubmitOptions, runMokaSubmitFromCli } from "./submit-options.js";
+import { Effect } from "effect";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { execa } from "execa";
-import { Command, Help, Option } from "commander";
+import { Command, Help, Option as Option$1 } from "commander";
 //#region src/cli/program.ts
 /**
 * Config-driven `execute` entrypoint. Package-owned defaults are the source of
@@ -35,7 +39,12 @@ function execute(description, options = {}) {
 		return runConfiguredPipeline({
 			pipelineRunner: options.pipelineRunner,
 			entrypoint: options.entrypoint,
+			runId: options.runId,
+			runStoreMode: options.runStoreMode,
+			runControl: options.runControl,
 			schedule: options.schedule,
+			supervised: options.supervised,
+			supervisor: options.supervisor,
 			task: description,
 			workflow: options.workflow,
 			worktreePath
@@ -47,7 +56,11 @@ function execute(description, options = {}) {
 function quick(description, options = {}) {
 	return execute(description, {
 		...options,
-		entrypoint: "quick"
+		entrypoint: "quick",
+		runControl: {
+			...options.runControl,
+			effort: "quick"
+		}
 	});
 }
 function withRunId(inputs) {
@@ -100,18 +113,117 @@ async function runConfiguredPipeline(rawInputs) {
 }
 async function runAndPrintPipeline(inputs) {
 	const runner = inputs.pipelineRunner ?? runPipelineFromConfig;
-	const reporter = createTerminalRuntimeReporter();
-	const result = await runner({
-		config: inputs.config,
+	const runStoreReporter = await createRunStoreReporter(inputs, createTerminalRuntimeReporter());
+	if (inputs.supervised) console.log(formatSupervisedRunFollowUp(requireRunId(inputs.runId)));
+	let result;
+	try {
+		result = await runWithFlushedReporter(runStoreReporter.flush, () => runner({
+			config: inputs.config,
+			reporter: runStoreReporter.reporter,
+			entrypoint: inputs.entrypoint,
+			runId: inputs.runId,
+			task: inputs.task,
+			workflowId: inputs.workflow,
+			worktreePath: inputs.worktreePath
+		}));
+	} catch (error) {
+		throw runtimeErrorWithFollowUp(error, inputs);
+	}
+	console.log(formatRuntimeResult(result));
+	if (result.outcome !== "PASS") throw new Error(formatRuntimeFailureWithFollowUp(result, inputs));
+}
+async function runWithFlushedReporter(flush, run) {
+	try {
+		return await run();
+	} finally {
+		await flush();
+	}
+}
+async function createLocalRunStoreRuntimeReporter(inputs, reporter) {
+	const runId = requireRunId(inputs.runId);
+	await createRun({
+		...resolvedRunControlOptions(inputs.runControl),
+		nodeIds: plannedRunStoreNodeIds(inputs),
+		runId,
+		workspaceRoot: inputs.worktreePath
+	});
+	return createRunStoreRuntimeReporter({
 		reporter,
-		entrypoint: inputs.entrypoint,
-		runId: inputs.runId,
-		task: inputs.task,
-		workflowId: inputs.workflow,
-		worktreePath: inputs.worktreePath
+		runId,
+		workspaceRoot: inputs.worktreePath
 	});
-	console.log(formatRuntimeResult(result));
-	if (result.outcome !== "PASS") throw new Error(formatRuntimeFailure(result));
+}
+function createRunStoreReporter(inputs, reporter) {
+	if (inputs.runStoreMode === "reuse") {
+		const runId = requireRunId(inputs.runId);
+		if (inputs.supervisor) {
+			const supervisor = createRunControlSupervisor({
+				reporter,
+				runId,
+				workspaceRoot: inputs.worktreePath
+			});
+			supervisor.start();
+			return {
+				flush: supervisor.stop,
+				reporter: supervisor.reporter
+			};
+		}
+		return createRunStoreRuntimeReporter({
+			reporter,
+			runId,
+			workspaceRoot: inputs.worktreePath
+		});
+	}
+	return createLocalRunStoreRuntimeReporter(inputs, reporter);
+}
+function requireRunId(runId) {
+	if (!runId) throw new Error("Run id is required for local run-control persistence.");
+	return runId;
+}
+function resolvedRunControlOptions(input) {
+	return {
+		effort: input?.effort ?? "normal",
+		mode: input?.mode ?? "write",
+		target: input?.target ?? "local"
+	};
+}
+function plannedRunStoreNodeIds(inputs) {
+	if (inputs.pipelineRunner) return [];
+	const workflowId = resolveWorkflowSelection(inputs.config, inputs.workflow, inputs.entrypoint);
+	return compileWorkflowPlan(inputs.config, workflowId).topologicalOrder.map((node) => node.id);
+}
+function formatSupervisedRunFollowUp(runId) {
+	return [
+		`Run id: ${runId}`,
+		`Status: moka status ${runId}`,
+		`Logs: moka logs ${runId}`
+	].join("\n");
+}
+function formatDetachedRunFollowUp(runId) {
+	return [
+		`Run id: ${runId}`,
+		`Status: moka status ${runId}`,
+		`Logs: moka logs ${runId}`,
+		`Stop: moka stop ${runId}`
+	].join("\n");
+}
+function formatRuntimeFailureWithFollowUp(result, inputs) {
+	const message = formatRuntimeFailure(result);
+	if (!(inputs.supervised && inputs.runId)) return message;
+	return [
+		message,
+		"",
+		formatSupervisedRunFollowUp(inputs.runId)
+	].join("\n");
+}
+function runtimeErrorWithFollowUp(error, inputs) {
+	if (!(inputs.supervised && inputs.runId)) return error;
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error([
+		message,
+		"",
+		formatSupervisedRunFollowUp(inputs.runId)
+	].join("\n"));
 }
 function scheduledEntrypointId(config, workflowId, entrypointId) {
 	if (workflowId) return null;
@@ -124,13 +236,39 @@ function createCliProgram() {
 	const program = new Command();
 	program.name("moka").description("Submit work to Momokaya").version(readPackageVersion()).exitOverride();
 	const runAction = async (descriptionParts, flags) => {
+		const task = descriptionParts.join(" ");
+		const resolution = resolveMokaRun({
+			flags,
+			task
+		});
+		if (resolution.execution.kind === "remote-submit") {
+			printMokaSubmitResult(await runMokaSubmitFromCli(descriptionParts, remoteSubmitFlags(resolution.execution)));
+			return;
+		}
+		const runControl = {
+			effort: resolution.effort,
+			mode: resolution.mode === "read" ? "read-only" : "write",
+			target: resolution.target
+		};
+		if (flags.detach) {
+			await runDetachedResolvedTask(task, resolution.execution, runControl);
+			return;
+		}
+		await runLocalResolvedTask(task, resolution.execution, runControl);
+	};
+	program.command("run").description("Primary command: run a workflow from package-owned @oisincoveney/pipeline config").argument("<description...>", "task description").option("--command", "treat input after -- as explicit argv for remote submission").option("--entrypoint <entrypoint>", "entrypoint alias from package config").option("--detach", "start a supervised controller process in the background").addOption(new Option$1("--effort <effort>", "run effort").choices([...MOKA_RUN_EFFORTS]).default("normal")).option("--read-only", "run the read-only inspect workflow").option("--schedule <schedule>", "approved schedule YAML to execute").addOption(new Option$1("--target <target>", "execution target").choices([...MOKA_RUN_TARGETS]).default("local")).option("--workflow <workflow>", "workflow id from package config").action(runAction);
+	program.command("run-controller", { hidden: true }).description("Internal detached run controller").argument("<description...>", "task description").requiredOption("--run-id <run-id>", "existing run id to supervise").option("--entrypoint <entrypoint>", "entrypoint alias from package config").option("--schedule <schedule>", "approved schedule YAML to execute").option("--workflow <workflow>", "workflow id from package config").action(async (descriptionParts, flags) => {
 		await execute(descriptionParts.join(" "), {
 			entrypoint: flags.entrypoint,
+			runId: flags.runId,
+			runStoreMode: "reuse",
 			schedule: flags.schedule,
+			supervised: true,
+			supervisor: true,
 			workflow: flags.workflow
 		});
-	};
-	program.command("run").description("Run a workflow from package-owned @oisincoveney/pipeline config").argument("<description...>", "task description").option("--entrypoint <entrypoint>", "entrypoint alias from package config").option("--schedule <schedule>", "approved schedule YAML to execute").option("--workflow <workflow>", "workflow id from package config").action(runAction);
+	});
+	registerRunControlCommands(program);
 	program.command("validate").description("Validate package-owned @oisincoveney/pipeline config and compile the workflow plan").option("--entrypoint <entrypoint>", "entrypoint alias from package config").option("--schedule <schedule>", "approved schedule YAML to validate").option("--strict", "fail when validation lint warnings are emitted").option("--no-lint", "skip validation lint warnings").option("--workflow <workflow>", "workflow id from package config").action((flags) => {
 		const cwd = process.env.PIPELINE_TARGET_PATH ?? process.cwd();
 		const config = loadPipelineConfig(cwd, { allowMissingLintFileReferences: true });
@@ -145,9 +283,9 @@ function createCliProgram() {
 		const config = loadPipelineConfig(cwd, { allowMissingLintFileReferences: true });
 		console.log(formatSelectedWorkflowPlan(config, cwd, flags));
 	});
-	program.command("doctor").description("Check local prerequisites for pipeline init and execution").option("--cluster [namespace]", "also check runner-job Kubernetes prerequisites").option("--kube-context <context>", "kubectl context for cluster checks").option("--kubeconfig <path>", "kubeconfig path for cluster checks").action(async (flags) => {
+	program.command("doctor").description("Check local prerequisites for pipeline init and execution").option("--cluster [namespace]", "also check runner-job Kubernetes prerequisites").option("--json", "print machine-readable readiness results").option("--kube-context <context>", "kubectl context for cluster checks").option("--kubeconfig <path>", "kubeconfig path for cluster checks").action(async (flags) => {
 		const result = await runDoctor(process.env.PIPELINE_TARGET_PATH ?? process.cwd(), flags);
-		console.log(formatDoctorResult(result));
+		console.log(flags.json ? JSON.stringify(result) : formatDoctorResult(result));
 		if (!result.passed) throw new Error("Doctor checks failed.");
 	});
 	const gatewayCommand = program.command("mcp").description("Manage the hosted-first MCP gateway").command("gateway").description("Inspect and configure the pipeline MCP gateway");
@@ -161,7 +299,7 @@ function createCliProgram() {
 		const config = loadPipelineConfig(process.env.PIPELINE_TARGET_PATH ?? process.cwd(), { allowMissingLintFileReferences: true });
 		console.log(renderGatewayConfig(config));
 	});
-	gatewayCommand.command("configure-host").description("Rewrite host MCP config to the singleton pipeline gateway").addOption(new Option("--host <host>", "host config to update").choices(["all", "opencode"]).default("all").argParser(parseGatewayHost)).addOption(new Option("--scope <scope>", "config scope to update").choices(["project", "global"]).default("project").argParser(parseGatewayHostScope)).action((flags) => {
+	gatewayCommand.command("configure-host").description("Rewrite host MCP config to the singleton pipeline gateway").addOption(new Option$1("--host <host>", "host config to update").choices(["all", "opencode"]).default("all").argParser(parseGatewayHost)).addOption(new Option$1("--scope <scope>", "config scope to update").choices(["project", "global"]).default("project").argParser(parseGatewayHostScope)).action((flags) => {
 		const cwd = process.env.PIPELINE_TARGET_PATH ?? process.cwd();
 		const result = configureGatewayHosts(loadPipelineConfig(cwd, { allowMissingLintFileReferences: true }), {
 			cwd,
@@ -189,14 +327,14 @@ function createCliProgram() {
 		const cwd = process.env.PIPELINE_TARGET_PATH ?? process.cwd();
 		console.log(await localGatewayStatus(cwd));
 	});
-	program.command("init").description("Initialize package-owned pipeline support without repo-local config").addOption(new Option("--skill-scope <scope>", "where to install default skills: project (repo-local copy) or personal (one inherited user/global install)").choices(["project", "personal"]).default("project")).action(async (flags) => {
+	program.command("init").description("Initialize package-owned pipeline support without repo-local config").addOption(new Option$1("--skill-scope <scope>", "where to install default skills: project (repo-local copy) or personal (one inherited user/global install)").choices(["project", "personal"]).default("project")).action(async (flags) => {
 		const result = await initPipelineProject({
 			cwd: process.env.PIPELINE_TARGET_PATH ?? process.cwd(),
 			scope: flags.skillScope
 		});
 		console.log(formatPipelineInitResult(result));
 	});
-	program.command("install-commands").description("Install generated slash-command adapters into this repository").addOption(new Option("--host <host>", "host command set to install").choices([
+	program.command("install-commands").description("Install generated slash-command adapters into this repository").addOption(new Option$1("--host <host>", "host command set to install").choices([
 		"all",
 		"opencode",
 		"claude-code"
@@ -216,14 +354,17 @@ function createCliProgram() {
 		console.log(formatCodexAuthSyncResult(result));
 		if (!result.ok) process.exitCode = 1;
 	});
-	addMokaSubmitOptions(program.command("submit").description("Submit work to Momokaya as an Argo Workflow").argument("[input...]", "task description, or command argv with --command")).action(async (input, flags) => {
-		const result = await runMokaSubmitFromCli(input, flags);
-		console.log(`Workflow submitted: ${result.workflowName} in ${result.namespace}`);
-		if (result.workflowUid) console.log(`Workflow UID: ${result.workflowUid}`);
+	addMokaSubmitOptions(program.command("submit").description([
+		"Submit work to Momokaya as an Argo Workflow.",
+		"Compatibility alias for `moka run \"<task>\" --target remote --effort thorough`.",
+		"Quick equivalent: `moka run \"<task>\" --target remote --effort quick`.",
+		"Command equivalent: `moka run --target remote --command -- <argv...>`."
+	].join("\n")).argument("[input...]", "task description, or command argv with --command")).action(async (input, flags) => {
+		printMokaSubmitResult(await runMokaSubmitFromCli(input, flags));
 	});
 	registerRunnerCommandCommand(program);
 	registerBenchCommand(program);
-	const configuredEntrypointCommands = registerConfiguredEntrypointCommands(program, omitConfiguredEntrypoints(configuredPipeline, ["execute", "quick"]), async (entrypoint, task, _opts) => {
+	const configuredEntrypointCommands = registerConfiguredEntrypointCommands(program, compatibilityPresetDescriptions(configuredPipeline), async (entrypoint, task, _opts) => {
 		await execute(task, { entrypoint });
 	});
 	if (configuredEntrypointCommands.size > 0) program.configureHelp({ subcommandTerm(command) {
@@ -232,6 +373,107 @@ function createCliProgram() {
 	} });
 	return program;
 }
+function runLocalResolvedTask(task, execution, runControl) {
+	return execute(task, {
+		entrypoint: execution.entrypoint,
+		runControl,
+		schedule: execution.schedule,
+		supervised: true,
+		workflow: execution.workflow
+	});
+}
+async function runDetachedResolvedTask(task, execution, runControl) {
+	const worktreePath = process.env.PIPELINE_TARGET_PATH ?? process.cwd();
+	const runId = generateRuntimeRunId();
+	const prepared = await prepareDetachedRun({
+		config: loadPipelineConfig(worktreePath, { allowMissingLintFileReferences: true }),
+		execution,
+		runId,
+		task,
+		worktreePath
+	});
+	await createRun({
+		...resolvedRunControlOptions(runControl),
+		nodeIds: plannedRunStoreNodeIds({
+			config: prepared.config,
+			entrypoint: prepared.entrypoint,
+			runId,
+			runControl,
+			schedule: prepared.schedule,
+			task,
+			workflow: prepared.workflow,
+			worktreePath
+		}),
+		runId,
+		workspaceRoot: worktreePath
+	});
+	const launch = await startDetachedRunController({
+		entrypoint: prepared.entrypoint,
+		runId,
+		schedule: prepared.schedule,
+		task,
+		workflow: prepared.workflow,
+		workspaceRoot: worktreePath
+	});
+	await updateRunController({
+		controller: {
+			argv: launch.argv,
+			cwd: worktreePath,
+			paths: runControlStatusPaths({
+				runId,
+				workspaceRoot: worktreePath
+			}),
+			pid: launch.pid,
+			startedAt: launch.startedAt
+		},
+		runId,
+		workspaceRoot: worktreePath
+	});
+	console.log(formatDetachedRunFollowUp(runId));
+}
+async function prepareDetachedRun(input) {
+	if (input.execution.schedule) {
+		const schedule = resolve(input.execution.schedule);
+		const compiled = compileScheduleArtifact(input.config, parseScheduleArtifact(readFileSync(schedule, "utf8"), schedule), input.worktreePath);
+		return {
+			config: compiled.config,
+			schedule,
+			workflow: compiled.workflowId
+		};
+	}
+	const scheduledEntrypoint = scheduledEntrypointId(input.config, input.execution.workflow, input.execution.entrypoint);
+	if (!scheduledEntrypoint) return {
+		config: input.config,
+		entrypoint: input.execution.entrypoint,
+		workflow: input.execution.workflow
+	};
+	const result = await generateScheduleArtifact({
+		config: input.config,
+		entrypointId: scheduledEntrypoint,
+		runId: input.runId,
+		task: input.task,
+		worktreePath: input.worktreePath
+	});
+	console.log(`Schedule generated: ${result.path}`);
+	const schedule = resolve(input.worktreePath, result.path);
+	const compiled = compileScheduleArtifact(input.config, parseScheduleArtifact(readFileSync(schedule, "utf8"), result.path), input.worktreePath);
+	return {
+		config: compiled.config,
+		schedule,
+		workflow: compiled.workflowId
+	};
+}
+function remoteSubmitFlags(execution) {
+	return {
+		command: execution.command,
+		quick: execution.mode === "quick",
+		schedule: execution.schedule
+	};
+}
+function printMokaSubmitResult(result) {
+	console.log(`Workflow submitted: ${result.workflowName} in ${result.namespace}`);
+	if (result.workflowUid) console.log(`Workflow UID: ${result.workflowUid}`);
+}
 function readPackageVersion() {
 	const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
 	if (typeof packageJson.version !== "string") throw new Error("Unable to read @oisincoveney/pipeline package version.");
@@ -240,11 +482,18 @@ function readPackageVersion() {
 function loadConfiguredEntrypoints(cwd) {
 	return loadPipelineConfig(cwd, { allowMissingLintFileReferences: true });
 }
-function omitConfiguredEntrypoints(config, ids) {
-	const omitted = new Set(ids);
+function compatibilityPresetDescriptions(config) {
+	const descriptions = {
+		execute: "Compatibility preset for `moka run --effort thorough`: full planner-generated pipeline for repository work",
+		inspect: "Compatibility preset for `moka run --read-only`: read-only repository inspection",
+		quick: "Compatibility preset for `moka run --effort quick`: compact planner-generated pipeline for small work"
+	};
 	return {
 		...config,
-		entrypoints: Object.fromEntries(Object.entries(config.entrypoints).filter(([id]) => !omitted.has(id)))
+		entrypoints: Object.fromEntries(Object.entries(config.entrypoints).map(([id, entrypoint]) => [id, descriptions[id] ? {
+			...entrypoint,
+			description: descriptions[id]
+		} : entrypoint]))
 	};
 }
 function parseGatewayHostScope(value) {
@@ -255,77 +504,15 @@ function parseGatewayHost(value) {
 	if (value === "all" || value === "opencode") return value;
 	throw new Error("host must be all or opencode");
 }
+function runCliEffect(argv) {
+	return Effect.tryPromise({
+		catch: (error) => error,
+		try: () => createCliProgram().parseAsync(argv, { from: "node" })
+	}).pipe(Effect.asVoid);
+}
 async function runCli(argv) {
 	await createCliProgram().parseAsync(argv, { from: "node" });
 }
-async function runDoctor(cwd, options = {}) {
-	const commandChecks = await Promise.all([
-		checkCommand("npx", ["--version"], cwd),
-		checkCommand("opencode", ["--version"], cwd),
-		checkCommand("fallow", ["--version"], cwd)
-	]);
-	const configCheck = checkPipelineConfig(cwd);
-	const globalConfig = loadMokaGlobalConfig();
-	const clusterResult = options.cluster ? await runClusterDoctor({
-		kubeContext: options.kubeContext,
-		kubeconfigPath: options.kubeconfig ?? globalConfig?.momokaya.kubernetes.kubeconfig,
-		namespace: clusterNamespace(options.cluster, globalConfig?.momokaya.kubernetes.namespace)
-	}) : { checks: [] };
-	const checks = [
-		...commandChecks,
-		configCheck,
-		...clusterResult.checks
-	];
-	return {
-		checks,
-		passed: checks.every((check) => check.passed)
-	};
-}
-function clusterNamespace(value, configuredNamespace) {
-	return typeof value === "string" && value.length > 0 ? value : configuredNamespace ?? defaultClusterDoctorNamespace();
-}
-function checkCommand(name, args, cwd) {
-	return checkCommandWithRunner(name, name, args, cwd);
-}
-async function checkCommandWithRunner(name, command, args, cwd) {
-	try {
-		await execa(command, args, {
-			cwd,
-			stdin: "ignore"
-		});
-		return {
-			detail: "available",
-			name,
-			passed: true
-		};
-	} catch (err) {
-		const error = err;
-		return {
-			detail: (error.shortMessage || error.stderr || "not available").trim(),
-			name,
-			passed: false
-		};
-	}
-}
-function checkPipelineConfig(cwd) {
-	try {
-		loadPipelineConfig(cwd);
-		return {
-			detail: "valid",
-			name: "pipeline-config",
-			passed: true
-		};
-	} catch (err) {
-		let message = "invalid";
-		if (err instanceof PipelineConfigError) message = err.issues.map((issue) => issue.message).join("; ");
-		else if (err instanceof Error) message = err.message;
-		return {
-			detail: message || "missing or invalid",
-			name: "pipeline-config",
-			passed: false
-		};
-	}
-}
 function formatWorkflowPlan(config, worktreePath, workflowId) {
 	return formatCompiledWorkflowPlan(config, worktreePath, compileWorkflowPlan(config, workflowId));
 }
@@ -392,4 +579,4 @@ function formatList(label, items) {
 	return items?.length ? `${label}=${items.join(",")}` : "";
 }
 //#endregion
-export { createCliProgram, execute, quick, runCli, runDoctor };
+export { createCliProgram, execute, quick, runCli, runCliEffect };

package/dist/cli/run-resolver.js

@@ -0,0 +1,58 @@
+//#region src/cli/run-resolver.ts
+const MOKA_RUN_EFFORTS = [
+	"normal",
+	"quick",
+	"thorough"
+];
+const MOKA_RUN_TARGETS = ["local", "remote"];
+function resolveMokaRun(input) {
+	const flags = input.flags ?? {};
+	const effort = flags.effort ?? "normal";
+	const target = flags.target ?? "local";
+	const mode = flags.readOnly ? "read" : "write";
+	if (flags.command && target !== "remote") throw new Error("--command requires --target remote");
+	if (flags.detach && target !== "local") throw new Error("--detach requires --target local");
+	return {
+		effort,
+		execution: target === "remote" ? resolveRemoteSubmit(flags, effort) : resolveLocalRuntime(flags, effort),
+		mode,
+		target
+	};
+}
+function resolveRemoteSubmit(flags, effort) {
+	return {
+		command: flags.command,
+		kind: "remote-submit",
+		mode: effort === "quick" ? "quick" : "full",
+		schedule: flags.schedule
+	};
+}
+function resolveLocalRuntime(flags, effort) {
+	if (flags.schedule) return {
+		kind: "local-runtime",
+		schedule: flags.schedule
+	};
+	if (flags.workflow) return {
+		kind: "local-runtime",
+		workflow: flags.workflow
+	};
+	if (flags.readOnly) return {
+		kind: "local-runtime",
+		workflow: "inspect"
+	};
+	if (flags.entrypoint) return {
+		entrypoint: flags.entrypoint,
+		kind: "local-runtime"
+	};
+	if (effort === "quick") return {
+		entrypoint: "quick",
+		kind: "local-runtime"
+	};
+	if (effort === "thorough") return {
+		entrypoint: "execute",
+		kind: "local-runtime"
+	};
+	return { kind: "local-runtime" };
+}
+//#endregion
+export { MOKA_RUN_EFFORTS, MOKA_RUN_TARGETS, resolveMokaRun };

package/dist/commands/bench-command.js

@@ -1,6 +1,17 @@
 import { buildEvalReport, renderEvalReport } from "../bench/eval-report.js";
+import { Context, Effect, Layer } from "effect";
 import { readFileSync } from "node:fs";
 //#region src/commands/bench-command.ts
+var BenchCommandService = class extends Context.Tag("BenchCommandService")() {};
+const BenchCommandServiceLive = Layer.succeed(BenchCommandService, {
+	readResults: (path) => Effect.try(() => JSON.parse(readFileSync(path, "utf8"))),
+	writeReport: (report) => Effect.try(() => process.stdout.write(`${report}\n`))
+});
+const runBenchCommand = (options) => Effect.gen(function* () {
+	const service = yield* BenchCommandService;
+	const report = renderEvalReport(buildEvalReport(yield* service.readResults(options.results)));
+	yield* service.writeReport(report);
+});
 /**
 * PIPE-83.6: `moka bench` — score a flat single-agent baseline vs the pipeline
 * (and ablations) over a recorded run set. Runs are produced by executing the
@@ -9,10 +20,7 @@ import { readFileSync } from "node:fs";
 * comparison report.
 */
 function registerBenchCommand(program) {
-	program.command("bench").description("Score a flat single-agent baseline vs the pipeline over recorded bench runs").requiredOption("--results <path>", "JSON file: array of { task, variant, resolved, costTokens, wallMs }").action((options) => {
-		const records = JSON.parse(readFileSync(options.results, "utf8"));
-		process.stdout.write(`${renderEvalReport(buildEvalReport(records))}\n`);
-	});
+	program.command("bench").description("Score a flat single-agent baseline vs the pipeline over recorded bench runs").requiredOption("--results <path>", "JSON file: array of { task, variant, resolved, costTokens, wallMs }").action((options) => Effect.runPromise(Effect.provide(runBenchCommand(options), BenchCommandServiceLive)));
 }
 //#endregion
 export { registerBenchCommand };